How to write open-source in PHP 2: Rise value of your package with help of skeleton
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.
- What is quality of package?
- Does it solve my issue?
- Is it trustworthy?
- 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
- Go to repository on Github and click on Clone or download
- Then Download a ZIP
- Unzip the zip file to your local repository
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
directories and I'm ready to roll. This is because:
- I upgrade my packages more often then some
- and because my preferences and required code are evolving
- e.g. A new PHP version is out, I tune my continuous integration (CI) setup etc.
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:
- Quality - What is quality of package?
- Usability - Does it solve my issue? Is it easy to use?
- Trust - Is it trustworthy?
- Maintenance - How well maintained is it?
- all your PHP source code will go here
- musthave :)
- all tests for your code in
- basically 1:1 mirror, just every file has
- Quality: tested code is perceived better quality
- Trust: I don't have to hope that code works, I can trust the code
- here are all files that are ignored by composer (using the
- when somebody will install your package via
composer require you/your-package, they won't get these files downloaded to
- usually its metadata files and tests, because application of end user does not need them
- Usability: Since your package save some internet trafic and space on hard drives, it's a bit more usable.
- here are files, that you will have locally but won't be uploaded to the remote git repository
- for packages ignore
composer.lock, for applications rather not - on Stackoverflow you can find more detailed answer
/vendoris there, as dependencies are installed by composer
- Trust: Without this I would not trust you know anything about open-source.
- configuration for Scrutinizer - code quality and code coverage tool
- to enable it, login and new repository
- I recommend you to login in via Github, since it adds hooks to your repository
- it would be triggered every time your commit to master or create a PR
Code quality and coverage badges in README
- Quality: Tests are fine, but with 5 % coverage, they have no added value. When you have 90% coverage, you got attention. Also there is code quality score from 0 to 10. It tells you about code complexity, which is the most important. Simple code is easier to maintain and debug. I will show you how to get 10 with bit of practise later.
- configuration for Travis - continuous integration tool for tests
- to enable it, go register there and add the repository
- Trust: Do you have test but you don't run them for every change? How can I know the code works?
- list of dependencies
- also configuration for Packagist, where you need to add your package, so it can be installed by others
- to enable it, you have to:
- go there
- add repository
- go to settings of package, Integration and services and Add Service
- select "Packagist" and add your name and token from your user profile
- license goes here
- it's important to have it as every country has different default approach, when this file is missing
- MIT is the easiest to understand open-source license
- Usability: With licence, I know what I can do with the code. Usually everything.
- configuration for PHPUnit - testing tool
- this can be used either by end user or Travis
- Usability: I can run
vendor/bin/phpunitwith no manual configuration. It makes life easy.
- last but the most important - your welcome article for user
- THE MOST IMPORTANT FILE IN THE PACKAGE!
- Don't worry. We'll talk about writing a good readme later.
- Usability: If I understand the usage, I can rely to the issue I want to solve.
- Trust: Having code quality, Travis and coverage badges helps to identify the quality of the package.
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?
- Test are passing - GOOD
- There is stable tag with "?" coverage - CONFUSING
- Master has 89% test coverage - GOOD
- Last version is probably 2.5, but not sure. Do they update manually? - CONFUSING
- Why is master promoted on first place? Should I use that? - CONFUSING
From Doctrine2 repository.
- Test are passing - GOOD
- Code quality is 10 - GOOD
- Code coverage 93% test coverage - GOOD
- It has 166 downloads. Here it depends on the age of package. → Go check release date! - GOOD
- It's tagged and has stable version. - GOOD
What have we done today?
- Where to go when starting a new repository.
- What is the purpose meta files.
- How to enable online services that help us to build better code.
- We'll peek on coding standards.
- How do releases work a what is semantic versioning.
- How to pick min PHP version and package versions in composer.
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.