Windows_7_and_TortoiseGit_contribution_guide
- Windows 7 x64 bit operating system.
- Git 1.8.1 & TortoiseGit 1.8.4.
- Register at GitHub.
- Download & install Git.
- Download & install TortoiseGit.
Firstly, configure your GitHub page to fork the original OpenCV repository:
- Go to GitHub.
- Open the Itseez OpenCV page.
- 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:
- Open the
.git\hookssubfolder and renamepre-commit.sampletopre-commit:
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.
- 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:
- 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 be then automatically closed, once your pull request has been merged.
When creating a fork to the GitHub repository, you fork it as it is on that moment. However, when adding pull requests, on a later moment, you might want to add changes to merged stuff. Then you notice all of a sudden your fork doesn’t contain new commits from OpenCV repository, so you need to update your fork.
- Go to your openCV folder that is linked with your TortoiseGIT/GIT client.
- Open the GIT bash client (which is way less complicated than the TortoiseGIT interface for this.
- If your GIT doesn’t start up on the master branch, make sure to type in the command
- Create the upstream connection to be able to retrieve all changes
- Retrieving the changes of the remote master to your local master branch is easy by the following command
- Identical for the 2.4 branch of the remote to your local 2.4 branch. Do not forget to first checkout to the 2.4 branch, else this will screw up your master
- Close down the git bash client. Updating is identical to pushing changes of a bugfix.
- Right click on the folder and select push from TortoiseGIT interface.
- Make sure to select the push all branches. Press OK.
- Output will tell you that update of master and 2.4 branch was successful.
