History

OpenCV Development Process »

« Previous - Version 36/52 (diff) - Next » - Current version
Daniil Osokin, 2014-07-14 06:01 pm

Contents

How to contribute

We suppose that you've seen the http://opencv.org/contribute.html page, and now, as an enthusiastic coder, want to contribute some code. For that purpose OpenCV project now has a mirror on the GitHub, to simplify everybody's life! All the bug fixes, new functionality, new tutorials etc. should be submitted via the GitHub's mechanism of pull requests.

If you are not familiar with the mechanism - do not worry, it's very simple. Keep reading.

"Fork & Pull Request model" for code contribution

Short instruction

  1. Install Git.
  2. Register at GitHub. Create your fork of OpenCV repository https://github.com/Itseez/opencv (see https://help.github.com/articles/fork-a-repo for details).
  3. Choose a task for youself. It could be a bugfix, or some new code.
  4. Choose a base branch for your work. You have two options:
    1. 2.4 - the branch that will be used for future minor releases in the 2.4.x line. Choose it when fixing a bug that's reproducible in this branch, or when making performance optimizations relevant to it. 2.4 has been feature-frozen; as such, new functionality will not be accepted.
    2. master - the branch that will be used for the next major release of OpenCV (tentatively, 3.0). Choose it when adding new functionality, or for bugfixes/optimizations that don't apply to 2.4.
  5. Create a new branch (with a meaningful name) from the base branch you chose.
  6. Modify/add the code following our Coding Style Guide.
  7. When you are done, push your branch to your GitHub fork; then create a pull request from your branch to the base branch (see https://help.github.com/articles/using-pull-requests for details).

Links to "step-by-step" guide for popular systems and clients

Making a good pull request

Following these guidelines will increase the likelihood of your pull request being accepted:

  1. Scope your PR to one issue. Before submitting, make sure the diff contains no unrelated changes. If you want to cover more than one issue, submit your changes for each as separate pull requests.
  2. If you have added new functionality, you should update/create the relevant documentation, as well as add tests for it to the testsuite.
  3. Try not to include "oops" commits - ones that just fix an error in the previous commit. If you have those, then before submitting squash those fixes directly into the commits where they belong.
  4. Make sure to choose the right base branch and to follow the Style Guide for your code.

Testing and merging of pull requests

  1. Your pull request will be automatically tested by OpenCV's buildbot (testing status can be checked here: http://pullrequest.opencv.org). If any builders are failed, you should fix the issue. As you fix the code and push changes to your branch at github, buildbot reruns automatically. No need to close pull request and open a new one!
  2. Once all the builders are "green", one of OpenCV developers will review your code. Reviewer could ask you to modify your pull request. Please provide timely response for reviewers (within weeks, not months), otherwise you submission could be postponed or even rejected.

Here is the flow-chart of the process:

Happy End

  1. As soon as the reviewer is fine with the pull request and BuildBot likes your code, the special comment ":+1:" or ":shipit:" is put, which signals OpenCV maintainers that they can merge your pull request.
  2. The last, but not least. Make sure you got credits. We try to memorize all the contributions and list major ones in the ChangeLog and release announcements, but we may forget to do that, unintentionally. Please, do not hesitate to remind us, and we will update opencv.org and the ChangeLog accordingly.

"Step-by-step" guide for popular systems and clients

Windows 7 and TortoiseGit

System configuration:

  • Windows 7 x64 bit operating system.
  • Git 1.8.1 & TortoiseGit 1.8.4.

Prerequisites:

  1. Register at GitHub.
  2. Download & install Git.
  3. Download & install TortoiseGit.

Firstly, configure your GitHub page to fork the original OpenCV repository:

  1. Go to GitHub.
  2. Open the Itseez OpenCV page.
  3. Press the fork icon on the right hand top side of the page:

Create a folder on your system to sync up the OpenCV source code from your fork:

  • Create a folder named 'opencv_source' in your systems root path (or your own selection).
  • Right click on the folder, selecting the Git Clone option:

  • Fill in the proper information into the configuration panel. Replace "StevenPuttemans" username with your GitHub username and remove the extra opencv folder that is added to the directory structure:

  • Press OK and let the folder sync up, until full synchronization has passed:

Create a new branch on your Git repository, to apply changes. Do not forget to create a new branch for every single update you want to do! These branches are local, but will be pushed to github after editing the source code.

  • Right click on folder.
  • Select TortoiseGit > Create Branch:

Select the correct options, choose a correct name for your branch, base it on the master branch for complete new functionality, or for minor fix, base it on 2.4 branch:

  • Hit the OK button and let it configure your repository. Changes might not change immediatly on the GitHub page, because it sync's in a lapsed time interval. Don't worry about that.

Select the file you want to adapt (in our case it's an adding extra comment to a source code file), adapt the the file accordingly and commit it to your GitHub repository.

  • In your configured GitHub folder on your machine, adapt the file you want.
  • In our case, we open up the file C:\opencv_source\apps\traincascade\traincascade.cpp.
  • Add your lines of code to the source code:

  • Save the file so that your adaptations are stored onto the system.
  • Your folder will indicate that a change has been made, by placing an exclamation mark:

  • Commit your adapted file to GitHub by selecting the commit->bugfix_1 option:
  • The first time, the system will ask you to input your username and email, giving the following warning. Press Yes, fill in credentials and press OK:

  • A commit window of TortoiseGit will appear, showing you the files that were adapted. It requires you to give a complete but brief description of your adaptation, then allows you to push the file. Select only the files you want to commit to the repository!

  • At the next window, explicitly tell the software to push the adaptations!

  • An interface will pop up to push the data and local branches (which you made earlier). Be sure to select the option to push all branches:

Your system is now all sync'd up with GitHub, lets make sure by checking.

  • The branch you created for the fix should be visible in the branch setup. Select the one you just created:

  • Check the file and see if adaptations worked. Also check if other branches stay clear of changes, which should be if you did everything correct:

Last step, creating a pull request!

  • Go to the GitHub website and open your own repository.
  • Click on the pull-requests button:

  • Push the 'new pull request' button:

Since we have only a comment to add, we would like to select the 2.4 branch, not the master branch, which is for future functionality mainly, not for small bugfixes.

  • Start by selecting the option to compare over forks:

  • Then select the correct branches of each fork to compare. For StevenPuttemans/opencv it's 'bugfix_1' and '2.4' for the Itseez/opencv:

  • Immediatly we can see, that there is a single file found, which is different between the current '2.4' branch on Itseez/opencv and the 'bugfix_1' branch on StevenPuttemans/opencv. We now assign a pull request at this change (which is basically asking to upload your code to the sourcecode of OpenCV).
  • Click to create a pull request at the designated button (see previous image).
  • Do not forget to add some explanation on what your add-on does exactly. Then click the send pull request button:

  • This all will result in an actual pull request being pushed towards the source code manager. Congratulations!. Now wait and go check from time to time, to make sure the developpers don't ask you to change something drastically:

A last step you should consider, is going back to the Issue tracker and add the link to your pull request at the actual bugfix task. The bug will then be automatically closed, once your pull request has been merged.