Open Source projects are gaining more momentum every day, new ones are appearing, popular ones are actively developing.
Projects such as Bootstrap , Angular.js , Elasticsearch , Symfony Framework , Swift, and many others are attracting new developers, their community is growing. All this gives a huge growth to projects, and the developers themselves are interested in participating in the development of something that the whole world uses.

I, like many other programmers, did not resist and also from time to time participate in the development of Open Source projects, mainly in PHP. But when I started, I ran into a problem - I didn’t know how to properly organize the process of “connecting”, where to start, how to make my pull request, etc.

All novice "distributors" who are faced with similar problems, welcome to the cat.
')


The very process of participation in the Open-Source project will consider the examples of various PHP frameworks, take Symfony , Yii2 .

The first thing you need to do is create an account on GitHub (if you don’t have one yet). Fill it carefully, as your GitHub profile is actually your business card in the world of Open Source.

Next, you should read the rules of participation in the development of your chosen project. These rules are usually found in the file.

CONTRIBUTING.md

at the root of the repository. For symfony, for example, this is symfony contributing .

Usually, there are several ways to participate in the development of the Open Source project, the main ones are to send a message about some error or desired improvement ( Submitting Issue ) or directly create a Pull Request with your Code Contributing . You can also participate in improving the documentation, answering questions from other developers, and much more.

Dispatch Issue

If you want to notify the developers of any bug or improvement found, you need to create an appropriate GitHub Issue. But before you create it, check whether there is already the same or similar, created by someone else. Before creating also do not forget to read the rules for sending an error report for this project. For example, here are the rules for the Yii Framework . Usually the description should be as clear as possible, understandable, it is desirable to have examples and descriptions of how to reproduce the error. This will save a lot of time for both developers and you, as it will save you from answering clarifying questions, etc.

Sending Pull Request

If you find a GitHub Issue that you would like to fix or have created your own, then your next step will be to send the appropriate Pull Request.

Again, for starters do not forget to familiarize yourself with the rules of participation in the development for the project you have chosen.
For example, here are the rules for Yii .

Further, I would like to describe the most frequently encountered process of working with Git and GitHub with participation in Open Source projects ( Git Workflow ).

This process may differ from project to project, and in general it is inherent not only to Open Source projects, but also to many closed projects on GitHub and BitBucket.

Step 1 - Preparing the Work Environment

Naturally, for development you need to prepare your working environment. Many open source projects indicate exactly how to configure it, which libraries, packages, tools, their versions, etc. are needed.

For PHP projects, you usually need about this minimal list.

• Git;
• PHP; (Usually versions from 5.3+)
• MySQL;
• Composer.

In addition, PHPUnit is often needed. Usually it goes as part of the project itself and it is better to use it, since in different versions of PHPUnit tests may simply not work and what works for you from the newest version may not work on the project CI server, where the library is older.

Step 2 - Create a copy (Fork) of the project repository

We go to the page of the project you have chosen and press the "Fork" button. This command will create your own copy of the repository of this project.



Next you need to clone your copy of the repository.

git clone https://github.com/<-GitHub->/<->.git 

Next you need to add an upstream branch for the project, which will refer to the base repository (option for Yii)

 cd <--> git remote add upstream https://github.com/yiisoft/yii2.git 

Step 3 - Configure Git

Next, you need to make a small setup of your Git, so that when you send commits, your correct name is displayed.
To do this, simply execute these commands:

 git config --global user.name " " git config --global user.email you@example.com 

If you want to adjust these values ​​locally for this project, in the project folder run

 git config --local user.name " " git config --local user.email you@example.com 

Step 4 - Composer

Further, in 99% of cases for a project, you will have to download libraries through Composer

 cd <--> composer install 

Step 5 - Tests

Before you start, set up your favorite IDE or simply PHPUnit console (less often Behat, PhpSpec, etc.) to start and work with tests.

After setup, run the tests for the project and check that they pass correctly.

Step 6 - Working with the code

Starting working on your fix, you first need to create an appropriate Git branch based on the actual code from the base repository.

Choose clearly and concisely the name of the branch, which would reflect the essence of the changes.
It is considered good practice to include GitHub issue number in the branch name.

 git fetch upstream git checkout -b 1234-helper-class-fix upstream/master 

Now you can safely get to work on the code.
When working, remember the following rules:

• Follow coding standards (usually PSR standards);
• Write unit tests to prove that a bug has been fixed, or that a new feature actually works;
• Try not to violate backward compatibility unless absolutely necessary;
• Use simple and logically whole commits;
• Write clear, clear, complete messages when committing changes.

Step 7 - Send Pull Request

While you were working on the code, other changes could be made to the main branch of the project. Therefore, before submitting your changes, you need to rebase your branch.
This is done like this:

 git checkout <--> git fetch upstream git rebase upstream/master 

Now you can submit your changes.

 git push origin <--> 

After that, go to your repository-clone of the project in which you participate and click the "New Pull Request" button.
And we see the following form:



On the left, you need to select the branch to which you want to merge the changes (usually this is master, well, in general, this is the branch to which you rebase).
On the right - a branch with your changes.
Next you will see a message from GitHub about whether it is possible to automatically merge the changes or not.
In most cases, you will see Able to merge.
If there are conflicts, you will most likely have to revise your changes.

Next, click the button - Create Pull Request.
When filling out the name and description of your pull request, it is considered good practice to indicate the Issue number for which your pull request was created.

Usually for many large projects a CI server is configured, often Travis-CI.

After creating the pull request, it will run tests, perhaps some tools for metrics, and so on. You will see the results of his work in your pull request as shown below:



If the tests fail or the build is not built, you will see a red error message and you can see what exactly is wrong with the Details link. In most cases, you will need to fix your pull request so that all checks are successful.

Step 8 - Recycle Pull Request

If everything is fine with your Pull Request, then soon it will be dealt with by someone from the team.
But it often happens that developers will ask you to make some changes.

To do this, simply return to step 6 and after making changes and commit, execute similar commands:

 git checkout <--> git fetch upstream git rebase upstream/master git push origin <--> 

Note: Personally, I like to send pull requests with only 1 commit. For this, I am doing a “squash” of unnecessary commits. How to do this can be found here: gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html

Step 9 - We're cleaning up after ourselves

After your Pull Request has been accepted or rejected, you need to delete the branch with your changes.
This is done simply

 git checkout master git branch -D <--> git push origin --delete <--> 

Instead of the last command, you can also execute

 git push origin :<--> 

Conclusion

Perhaps this is all that concerns the basic things of participation in Open Source projects.

I would like to add that you are not lazy and participated in Open Source projects. This is a great and interesting experience, as well as a tick in the resume.

Also for PHP developers there is an excellent guide on how to contribute to symfony, it will be useful not only when working with symfony: symfony.com/doc/current/contributing/index.html

Thanks to all!