Understanding Github and Pull Requests

Github is a very powerful and flexible collaboration tool that can seem non-intuitive for those just starting out. For those willing to volunteer their time working on the ZoneMinder project, knowing how to use Github is an absolute requirement. With a little time and practice, you may find yourself wondering how you ever survived without it!

The following instructions attempt to simplify the learning curve required to generate a clean pull request. These steps apply to modifications of the ZoneMinder project, which are relatively small to moderate in scope and do not take a lot of time to complete.

Your very first Pull Request

1. Create a Github account and log into the Github web portal.
2. From the web portal, fork the ZoneMinder project by clicking the fork button at the top-right of the page.
   • See the official Github documentation for forking a repo here.
   • Think of this merely as cloud-based storage to hold your work, which will be done from your local drive.
   • Do not worry about keeping your remote fork "in-sync". That will not be necessary.
3. Clone your remote fork to your local disk.
   • See the official Github documentation for forking a repo here.
   • Execute the following from the command line: git clone https://github.com/YOUR-USERNAME/ZoneMinder.git
   • This will map your fork on Github to the name "origin". Remember that.
4. Change into the newly created ZoneMinder folder and create a second mapping that points to the official ZoneMinder remote repository.
   • Execute the following from the command line: git remote add upstream https://github.com/ZoneMinder/ZoneMinder.git
   • This will map the official ZoneMinder repository on Github to the name "upstream". Remember that.
5. Backup your config.
   • Git keeps its configuration under a hidden folder called .git.
   • Copy ZoneMinder/.git/config to a safe location. If you ever need to start over, you can skip the steps you just performed by restoring that config file.
6. Make sure you are in the master branch: git checkout master
7. Make sure your master branch is up to date with the ZoneMinder project: git pull upstream master
8. Create a new branch to perform your work: git checkout -b my_new_branch
   • Never work from the master branch
9. Make your proposed changes.
   • As you progress, make commits in a logical manner.
   • Lumping everything into a single, large commit should be avoided. Others have to read your work!
10. Commit changes using a series of these commands:
    • git add [names of modified files] or git add .
    • git commit
    • Pay attention to which files are part of each commit. Sometimes unexpected files can sneak in, especially if you used wildcards with your git add commands.
11. When finished, push your changes to your fork on Github: git push origin my_new_branch
12. Navigate to the Github web site. If you are already there, you may need to refresh your browser.
    • You are looking for a message from Github, acknowledging you just pushed a new branch to your fork and asking if you want to perform a Compare.
13. Push the Compare button.
14. Verify the title, description, and content look correct.
15. Generate a Pull Request.

This is what the command line steps look like without the commentary:

git clone https://github.com/YOUR-USERNAME/ZoneMinder.git
cd ZoneMinder
git remote add upstream https://github.com/ZoneMinder/ZoneMinder.git
cp ./.git/config ~/config.bak
git checkout master
git pull upstream master
git checkout -b my_new_branch
[ make your edits ]
git add .
git commit
git push origin my_new_branch

Subsequent Pull Requests

1. From the command line, navigate to the ZoneMinder repository on your local disk
2. Verify you are in the master branch: git checkout master
3. Make sure your local master branch is up to date with the master branch in the ZoneMinder repository (not your fork): git pull upstream master
   • This is the critical step that many overlook. Not getting this right, will cause problems later on.
4. Create a new branch to perform your work: git checkout -b my_new_branch
   • Never work from the master branch
5. Make your proposed changes.
   • As you progress, make commits in a logical manner.
   • Lumping everything into a single, large commit should be avoided. Others have to read your work!
6. Commit changes using a series of these commands:
   • git add [names of modified files] or git add .
   • git commit
   • Pay attention to which files are part of each commit. Sometimes unexpected files can sneak in, especially if you used wildcards with your git add commands.
7. When finished, push your changes to your fork on Github: git push origin my_new_branch
8. Navigate to the Github web site. If you are already there, you may need to refresh your browser.
   • You are looking for a message from Github, acknowledging you just pushed a new branch to your fork and asking if you want to perform a Compare.
9. Push the Compare button.
10. Verify the title, description, and content look correct.
11. Generate a Pull Request.

This is what the command line steps look like without the commentary:

cd ZoneMinder
git checkout master
git pull upstream master
git checkout -b my_new_branch
[ make your edits ]
git add .
git commit
git push origin my_new_branch

IMPORTANT NOTES

1. Do not worry about breaking the project with your pull request. You literally don't have permission to do that directly, and it is up to the development team to properly review your work before merging.
2. If you receive unexpected results, that is often due to not performing a critical task, or performing that task incorrectly, at the beginning of the process.
3. Follow these steps exactly. Do not skip any steps. There is a lot of other Github documentation out there, which may describe something a little different. Do not be distracted by that.
4. Because all the real work is being done on the local drive, we don't care if your fork on the Github site is in-sync with the ZoneMinder project or not.
5. For the sake of what is described here, don't ever work out of your own master branch, local or remote. Working from your own master branch can cause problems later on in the process.