How to write open-source in PHP 2: Rise value of your package with help of skeleton

After creating a repo, we have to fill it with something useful. Our code! Of course, but we also need some metadata files. What are they for? Is there some prepared code we can use? What are badges for? I will answer all these questions today.

Other programmers who want to use your package are usually looking for long term value. To estimate the value they need to answer 4 important questions.

  1. What is quality of package?
  2. Does it solve my issue?
  3. Is it trustworthy?
  4. How well maintained is it?

Even if you know your code is the best and the cleanest, if they don't trust you, they will never use it.

I will let you think about them a little bit. We will relate with specific files to them in second part of this article.

Use solid skeleton → start solid brand

Now, the first step that can positively influence all the 4 answers is using a skeleton with prepared metadata files. Guys from The PHP League already did the job for you and created a skeleton package. From my point of view, there is too much unnecessary code, so I've prepared clear version for you.

Pick one you understand the best.

How to get skeleton code to your local repository in 4 steps

  1. Go to repository on Github and click on Clone or download
  2. Then Download a ZIP
  3. Unzip the zip file to your local repository
  4. And push new files to Github

    git add .
    git commit -m "add metadata files"
    git push origin master

Great for start, yet obsolete later

This skeleton is great for start and to learn about metadata files.

But when I create my package now, I just copy the most recent package I made, delete /src and /tests directories and I'm ready to roll. This is because:

What is the purpose of these files

Now we look on every directory and file and how it's related to the 4 key questions. Just to remind you, the end user is interested in:

  1. Quality - What is quality of package?
  2. Usability - Does it solve my issue? Is it easy to use?
  3. Trust - Is it trustworthy?
  4. Maintenance - How well maintained is it?

/src directory

Meaning

Profit

/tests directory

Meaning

Profit

.gitattribues

Meaning

Profit

.gitignore

Meaning

Profit

.scrutinzer.yml

Meaning

Profit

Code quality and coverage badges in README
Code quality and coverage badges in README


.travis.yml

Meaning

Profit

composer.json

LICENSE

Meaning

Profit

phpunit.xml

Meaning

Profit

README

Meaning

Profit

So that are all files and their purpose.

No time! Fast! Now! → Tell your story with an image

Today people are scanning the text rather then actually reading. That's why badges are so important!

Look on these 2 - what information can we get?

Confusing badge

From Doctrine2 repository.

Well informative badge

From Symplify/ControllerAutowire repository.

What have we done today?

What's next?


Hate me, please!

Did you came across some error or wtf? Is it boring, too long or too vague? Just send me a comment. I want to make this series bulletproof and as helpful as possible.

You will help thousands of others if you help me to fix one issue.

Thank you!



What do you think?