Contributing to a project is awesome! However it might be difficult to know exactly how to do it or what need to be done. This contributor guide will help you to make great contributions!
Table of contents
- What to do?
- Set up the environment
- Validating a patch
- Commiting a patch
- Publishing a patch
- Contributor pack
Hoa is a big project. This project cannot live without the help of a precious community. This community is constitued of casual developers, regular developers, sometimes even people that are not developers but programming lovers, people used to use PHP, sometimes not…
Every experience, every idea, every thing that can make Hoa better for thousands of users world-wide is inestimable. However, contributing to a project is not an easy task. There is some prerequisites, some useful information to be aware of, like:
- The organization,
- Who are the people to talk to, and,
- In a more simpler way, what to do exactly?
We hope this contributor guide will answer to these questions.
Before contributing to Hoa, we need to clarify some requirements in terms of tools, skills etc. in order to make your journey as much pleasant as possible.
To contribute to Hoa, the following tools are required:
That's all. Every other tools are going to be automatically installed when needed.
This important point needs to be clarified quickly. There is absolutely no minimum skill level required to contribute to Hoa. If you have an idea but you don't know how to develop it: Never mind, just open a discussion and we will be very glad to help you understand how to do it! If you have a higher knowledge than us on a specific domain (which is likely to happen often), we will be very glad to learn from you! The community of Hoa is rich because it is consituted of very different people. We cannot wait for your first contribution!
Also, it is important to note we are going to show you some Git commands. Our goal is not to provide a Git guide. The given commands are the ones you are likely to use daily, but if you do not understand them or if you do not feel comfortable with Git, you must either read the Git documentation or ask help. This introduces the next section.
At anytime, you will find at least one person to help you. Hoa, as a set of libraries, is a vast project and not all hoackers are present all the time, but we are pretty sure you will meet someone that can help or redirect you to someone else. An hoacker is a long-term contributor that has deep or wide knowledge of the project. It includes reviewers and commiters.
Two ways to get help:
- on IRC, for a realtime and synchronous help,
- on mailing-lists, for an asynchronous help with more people.
What to do?
Hoa has more than 50 libraries, in addition to other sub-projects. Each library lives in a specific repository. This is hard to have an overview of the current work:
- What should be done?
- What is ready to be done?
- What is in progress? or
- What is under review?
They are all legitimate questions when starting with a project (even when you are a long-term contributor sometimes!).
Boards for an overview
Each library has a hack book chapter. Each chapter provides useful links to its top, such as:
- To its board,
- To its Git repository,
- To its Github mirror.
The board is the place where all the works appear in columns representing the progression:
- Backlog, things under discussion,
- Ready, things that are ready to be done,
- In progress, things that are being done by some contributors,
- Done, things that have been recently done.
Also, you may know that the
Central is a (read-only)
repository that gathers all Hoa's libraries in one place. So, as expected,
the board of the
provides the highest overview of all the current works of
all Hoa's libraries.
In order to ease the contribution process, we are trying to attach several
labels to each work (like
of them provide an information about the difficulty:
casual, can be done by a new contributor or can be done quickly,
medium, requires some skills to address this work,
hard, requires strong skills in the code and the domain it addresses.
Fortunately, boards provide a search engine easing to sort the works based on your profile; thus:
Now we know what to do, let's contribute!
Set up the environment
In this section we will see how to set up the repository (the code) and the dependencies (mostly to run the tests).
Hoa hosts its own Git repositories. The rules are the following:
- Everyone can read through HTTP:
$ git clone https://git.hoa-project.net/Library/Websocket.git
$ git clone firstname.lastname@example.org:Library/Websocket.git
As mentionned on the source page, most of the repositories are mirrored on Github. We use Github as a bug tracker, where all issues and contributions happen. Also, several tools are linked to Github such as the boards or Composer (detailed hereinafter). Mirrors are one-way and a bot is responsible to synchronize everything, no worry.
So we suggest you to start by cloning a library from Github, let's say
$ mkdir Hoa $ cd Hoa $ git clone https://github.com/hoaproject/Websocket.git $ cd Websocket
If Github knows your public SSH key, then we suggest:
$ git clone email@example.com:hoaproject/Websocket.git
Immediatly, to avoid incoming potential conflicts, we suggest to create a new branch:
$ git checkout -b incoming
incoming branch keeps the
branch safe. The
master is really important for
Hoa, because it uses the Rush Release as a
release system. It implies the
master branch always contains the
latest patches. Thus, to update the
master branch, you just need
$ git pull origin master:master
Because your reference branch is
incoming and not
master, this is easier to maintain your repository
up-to-date. We will detail this shortly.
Of course you will not work directly on Hoa's repository because: First, it
is a mirror, second, you do not have the permissions and third, it is a bad
practise. You need to
fork the repository.
A fork is a raw copy of the repository, allowing to do
whatever you want without any restrictions. To fork a repository, let's say
Hoa\Websocket, you can
use the Github
interface or run the following command (assuming the variable
$me represents your Github username):
$ me=<your Github username> $ curl -X POST https://api.github.com/repos/hoaproject/Websocket/forks --user $me
Now you have your own fork, we must tell the repository this is another remote. A remote is another location for a repository. Thus:
$ git remote add me firstname.lastname@example.org:$me/Websocket.git
At this point, we should see 2 remotes, like in the following example:
$ git remote --verbose me email@example.com:$me/Websocket.git (fetch) me firstname.lastname@example.org:$me/Websocket.git (push) origin email@example.com:hoaproject/Websocket.git (fetch) origin firstname.lastname@example.org:hoaproject/Websocket.git (push)
Bonus: If you would like to see all the pull requests locally, i.e. all the
contributions in progress (can be useful to help or test
someone else's contribution), we will create a new remote, called
github-pr. It will point to the same URL than
in this particular case but we create another remote to clarify the workflow.
$ git remote add github-pr email@example.com:hoaproject/Websocket.git $ git config remote.github-pr.fetch '+refs/pull/*/head:refs/remotes/origin/pr/*' $ git remote --verbose github-pr firstname.lastname@example.org:hoaproject/Websocket.git (fetch) github-pr email@example.com:hoaproject/Websocket.git (push) me firstname.lastname@example.org:$me/Websocket.git (fetch) me email@example.com:$me/Websocket.git (push) origin firstname.lastname@example.org:hoaproject/Websocket.git (fetch) origin email@example.com:hoaproject/Websocket.git (push)
So to sum up, we have 3 remotes, i.e. 3 different sources for the same code:
origin, Hoa's repository (Github mirror),
me, your fork,
github-pr, all pull requests on Hoa's repository.
Finally, to get all the data from all the remotes:
$ git fetch --all
The repository you cloned is likely to contain dependencies. To manage and install them, we rely on Composer. Thus, to install them:
$ composer install
And to update them:
$ composer update
vendor/ directory has been created at the root of the
repository, along with a
composer.lock file. Inside the
vendor/hoa/ directory you will find all Hoa's dependencies. And
vendor/bin/hoa file is a command to execute some programs
provided by Hoa. We will use them shortly.
In addition to the
incoming branch, it will be more
comfortable and less error-prone to create one branch per
contribution. There is no convention about the branch naming but we
recommend everything in lowercase and
/ instead of spaces. Before creating a new branch, it is
recommended to start with an up-to-date
$ git pull origin master:master $ git checkout incoming $ git merge master
Now you are ready to create your new branch, let's say
$ git checkout -b awesome-feature $ git branch * awesome-feature incoming master
You are now ready to start writing code.
Files that are likely to be modified are at the root of the repository. Edit them, save them, execute them, you are free to do whather you want. Assume that all files are UTF-8 encoded. This is important. If you need softwares to edit code, we can help you (see section bellow).
In the source page, we learn what is the structure of a library. You must read it.
Validating a patch
While you are coding, before commiting your patches, you need to validate them. Our advice is to repeat this operation very often. The more you validate your code, the easier it will be to detect and understand errors or faults.
Preparing a patch
Before all: Coding styles. Hoa adopts PSR-1 and PSR-2 standards regarding coding styles, in addition to some other internal standards. In order to check and automatically fix the majority of them, you would need to run the following command preferably at the root of the repository:
$ vendor/bin/hoa devtools:cs --dry-run --diff .
This command will check and print whether the majority of the coding styles
are respected. If you want to automatically
fix them, just remove the
--dry-run option; thus:
$ vendor/bin/hoa devtools:cs --diff .
hoa devtools:cs requires the
to be installed somewhere. Since this is a tool you might use accross several
projects, our advice is to install it globally:
$ composer global require fabpot/php-cs-fixer
Be ensured that
~/.composer/vendor/bin is present in your
Testing a patch
Once your code pretty, you can run tests to ensure there is no regression first; assuming you are still at the root of the repository:
$ vendor/bin/hoa test:run --directories Test/
Excellent! To write new tests, to
complete existing ones or to learn more about their
execution, please refer to the documentation of
Hoa\Test library. We do not require contributors to use a
specific development methodology, like test-driven development for instance.
You are free to do whatever you want.
Commiting a patch
Because credits are important, check that your name and email are provided in your Git configuration file:
$ git config --get user.name Gordon Freeman $ git config --get user.email firstname.lastname@example.org
If one of these values is empty, then you must set them (most of the time, globally, i.e. for all the repositories):
$ git config --global user.name 'Gordon Freeman' $ git config --global user.email 'email@example.com'
Now… commit as much as possible. Abuse of commits. It is not bad to have too much commits but it is unfortunate to not have enough of them. One commit is atomic, it includes one specific modification. At least, the code must be able to run between any commit.
The commit language is English. Its title must be 50 characters long. Its body must be formatted using Markdown (even Github flavored Markdown is accepted). A commit message tells a story. Feel free to add links and other references into the commit body. It must answer to the following questions:
- What was the issue?
- How to address this issue?
- How did we address the issue?
These questions reflect the way we do everything in Hoa (in particular the
documentation). We do not provide a
API” just to make the
“buzz”. We identify a problem, we think about
it, we think about several ways to address it, and finally we propose a way to
address it by scrupulously keeping the backward compatibility (BC) and
preventing future potential BC breaks. Sometimes it can be a long process but
this is really important.
Also, while forcing ourselves to answer these questions when writing a commit can be sometimes difficult or annoying, believe us, it will be really appreciated when they will be read later.
To precisely choose what is going to be included inside a commit, we recommend to always use the following workflow:
$ git add --patch <file> $ git add --patch <another file> … $ git commit
git commit has no argument because the patch has
been constructed with
git add. (We highly
recommend to use your editor —set by the
variable— to edit the commit message: It is not possible to fulfill our
recommendations in CLI).
To check what has changed, you can use the
$ git status --long
If you made a mistake while commiting, no worry, you are still able to edit your commit message by running:
$ git commit --amend
Do not edit the
CHANGELOG.md file. It is automatically
Review all your commits
Sometimes you will express the need to list all your
commits. Either you use the classical
git log command:
$ git log --decorate=full incoming..HEAD
Or you can use an enhanced
git log command that we are going
$ git config --global alias.graph "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative"
$ git graph incoming..HEAD
Publishing a patch
Even if it is not complete, publish your work! First, we are very happy to see people contributing to Hoa, even if it is not complete. Second, it provides an overview of what is in progress. And third, it will be easier for you to get help since people could follow your work proactively. So: Publish your contribution as soon as possible!
To publish your work, patches need to be pushed on your own fork. If you
mind correctly, the remote referring to your fork is called
You then need to push your
awesome-feature branch to your
$ git push me awesome-feature
Then, open your browser and go to your fork page on Github. A “pull request” button should appear shortly. Click on it and the magic happens. Let the Github interface guides you and create your pull request. A pull request means: You request us to pull your work, so in other words to merge your work. We often refer to pull request as PR.
Rebase when asked
We adviced you to commit as much as possible. But sometimes, it is too much and that is not a problem at all. Especially when you pushed your work, we discussed about it together and some new commits have been applied and pushed, the resulting history can be a little bit confusing. We like to have a clean history. So we may ask you to rebase your work: It means to rewrite the history. Most of the time, the operation consists to “squash” commits: You have 2 commits, you squash them, you obtain 1 commit. The easiest and safest way to do that is to use the interactive mode by running:
$ git rebase --interactive incoming
Be careful when doing this. This is unfortunately dangerous for your commits. When everything is clean, and because this is the latest request we might asked, you re-push your history. But because it differs from the remote history, you need to force it by running:
$ git push me awesome-feature --force
On ourside, we are ready to merge your contribution!
Note: If you are not familiar with
git rebase, ask help!
How your contributions will be reviewed? When the pull request is created, someone will be assigned to it shortly. Most of the time, this is going to be an hoacker. This person is in charge to:
- Guide you,
- Help you,
- Give you pointers and links to useful resources,
If you are lost, at any moment, ping the reviewer by writing its pseudo
@. A notification will be sent to her. Please, keep
in mind that everyone engaged in the Hoa project is a
volunteer and share its free time. If your reviewer seems to
be far away from keyboard, ping
to notify all hoackers at once. If you feel abused, ping them too.
If enought people are available, we like to do a double-review:
- The first reviewer has local and deep knowledges. By local we mean the repository (the library most of the time),
- The second reviewer comes later and has wide knowledges. She has a better overview of how the code need to be integrated.
We hope to give you two reviewers but this is not always the case.
Note: Being a reviewer is also a kind of contribution!
When your patches have been reviewed, it is time for the commiter to come
on stage! The commiter will fetch your pull request locally on its computer.
Then your patches will be merged and pushed
master branch on the
git.hoa-project.net remote. Finally, mirrors will be synced,
along with Github issues and pull requests. So far, there is very few
commiters for security reasons.
Big news: You are a contributor!
We love our community and we try to promote your work! Consequently, we maintain an exhaustive list of all contributors on the community page.
In addition to this list, we offer you the following “gifts” as part of the contributor pack:
- A mail address:
firstname.lastname@example.org its alias
- A PHPStorm license,
- An IRC cloak (allow to reserve your nickname on our channels),
- Some goodies during events,
- Invites and special offers to some events (if several contributors go to an event, we can ask special offers).
We have seen the classical workflow you might adopt as a contributor (new or not): What to do, how to do it, with who etc. We explained where you can get help, the people you are likely to talk to and how to contribute in the best way. Some tools have been introduced to help you, such as coding styles checker and fixer, testing etc. Finally, we introduced the contributor pack: A reward for your contributions!
We really hope you feel confident to start your first contribution!