Close search
Hoa

Contributor guide

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

  1. Introduction
  2. Prerequisites
    1. Tools
    2. Skills
    3. Getting help
  3. What to do?
    1. Boards for an overview
    2. What difficulty?
  4. Set up the environment
    1. Repository
    2. Dependencies
    3. New branch
  5. Validating a patch
    1. Preparing a patch
    2. Testing a patch
  6. Commiting a patch
    1. Review all your commits
  7. Publishing a patch
    1. Rebase when asked
    2. Reviewers
    3. Commiters
  8. Contributor pack
  9. Conclusion

Introduction

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:

We hope this contributor guide will answer to these questions.

Prerequisites

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.

Tools

To contribute to Hoa, the following tools are required:

That's all. Every other tools are going to be automatically installed when needed.

Skills

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.

Getting help

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:

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:

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:

The board is the place where all the works appear in columns representing the progression:

  1. Backlog, things under discussion,
  2. Ready, things that are ready to be done,
  3. In progress, things that are being done by some contributors,
  4. 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 Central provides the highest overview of all the current works of all Hoa's libraries.

What difficulty?

In order to ease the contribution process, we are trying to attach several labels to each work (like bug or enhancement). Some of them provide an information about the difficulty:

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).

Repository

Hoa hosts its own Git repositories. The rules are the following:

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 the Hoa\Websocket library:

$ 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 git@github.com:hoaproject/Websocket.git

Immediatly, to avoid incoming potential conflicts, we suggest to create a new branch:

$ git checkout -b incoming

Creating an incoming branch keeps the master 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 to run:

$ 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 git@github.com:$me/Websocket.git

At this point, we should see 2 remotes, like in the following example:

$ git remote --verbose
me  git@github.com:$me/Websocket.git (fetch)
me  git@github.com:$me/Websocket.git (push)
origin  git@github.com:hoaproject/Websocket.git (fetch)
origin  git@github.com: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 origin in this particular case but we create another remote to clarify the workflow. Thus:

$ git remote add github-pr git@github.com:hoaproject/Websocket.git
$ git config remote.github-pr.fetch '+refs/pull/*/head:refs/remotes/origin/pr/*'
$ git remote --verbose
github-pr   git@github.com:hoaproject/Websocket.git (fetch)
github-pr   git@github.com:hoaproject/Websocket.git (push)
me  git@github.com:$me/Websocket.git (fetch)
me  git@github.com:$me/Websocket.git (push)
origin  git@github.com:hoaproject/Websocket.git (fetch)
origin  git@github.com:hoaproject/Websocket.git (push)

So to sum up, we have 3 remotes, i.e. 3 different sources for the same code:

  1. origin, Hoa's repository (Github mirror),
  2. me, your fork,
  3. github-pr, all pull requests on Hoa's repository.

Finally, to get all the data from all the remotes:

$ git fetch --all

Dependencies

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

A 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 the vendor/bin/hoa file is a command to execute some programs provided by Hoa. We will use them shortly.

New branch

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 -, _ or / instead of spaces. Before creating a new branch, it is recommended to start with an up-to-date master and incoming branches:

$ git pull origin master:master
$ git checkout incoming
$ git merge master

Now you are ready to create your new branch, let's say awesome-feature:

$ 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 .

The command hoa devtools:cs requires the PHP-CS-Fixer tool 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 $PATH.

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 the 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
gordon@freeman.hl

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 'gordon@freeman.hl'

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:

  1. What was the issue?
  2. How to address this issue?
  3. 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 “cool” and “blazing fast 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

Note that git commit has no argument because the patch has been constructed with git add. (We highly recommend to use your editor —set by the $EDITOR environment 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 command:

$ 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 generated.

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 to call graph:

$ 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"

Thus:

$ 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 me. You then need to push your awesome-feature branch to your me remote:

$ 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!

Reviewers

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:

If you are lost, at any moment, ping the reviewer by writing its pseudo prefixed by @. 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 @hoaproject/hoackers 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:

  1. The first reviewer has local and deep knowledges. By local we mean the repository (the library most of the time),
  2. 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!

Commiters

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 to the 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!

Contributor pack

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:

Conclusion

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!

Comments

menu