How to contribute code to Centinel
You should not push to any Centinel repository or branch directly, even if you have enough privileges to do so. You can, however, send in pull requests to a repository from your own personal fork of Centinel. The pull request will be merged into Centinel after going through code review.
You are advised to follow these guidelines closely if you want to contribute to any ICLab repository. If you fail to do so, your code will not be merged into the repository.
In order to write code for Centinel (or other repos), you should maintain your own fork of the main repository. You can learn about forking on github here.
You can clone your code on your local machine by running this in your terminal:
git clone [your fork's address]
You should also add the remote repository (the one you forked from) to your local clone:
git remote add remote [original repo address]
git fetch
git fetch remote
Your setup should be ready for coding. Remember that the first two steps should only be done once when you want to initialize your local clone. These steps can be omitted when doing development later.
Before you fix a problem or add a feature, you have to make a branch for it on your local clone. To do so, you first have to make sure you are on the master branch of your local clone:
git checkout master
Then sync it up with the master branch of the remote repository you added earlier. You can do so by running:
git fetch remote
git pull remote master
Now you can create a branch for your code. Pick a meaningful name for your branch. If your are fixing a bug, you are advised to use a name like fix/ssl_fix. If you are adding a feature, you can use a name like feature/add_cert_check.
git branch [branch name]
git checkout [branch name]
You can now start writing code. Make sure your code follows coding convention used in the original repository. For Centinel, PEP8 compliance is mandatory. Refer to PEP8 manual for more information.
Keep your code clean and be sure to leave comments where necessary. Use config options for strings and numbers where possible (filenames, paths, etc.).
You can commit your code piece-by-piece. There is no need to bundle a large number of changes together for one commit. This makes it more difficult to rectify errors and follow the progress of the code.
You can add individual files to your commit by running:
git add [changed/added file name]
Important:
You should never run git add *! This is very likely to add unnecessary and unwanted files and garbage to your commit that might end up in the repository.
Pull requests containing garbage will be closed.
You can commit by running:
git commit
This will ask for a commit message. Make sure your commit message is descriptive yet concise (no more than one sentence). Avoid messages that are too general. Just describe what that one commit does or what it addresses. If you are addressing an issue by that commit, you can reference it in your commit message so that the issue can be automatically closed upon merging the pull request (look at this for more info). An example commit message that closes issue number 44 (found next to issue name on github):
Added ICMP tracerout to traceroute primitive. Fixes #44.
If you added a commit by mistake, you can reset back to any commit before it by getting a log of latest commits (along with their commit IDs) and reverting back using git reset:
git log
After you find the commit you want to revert to, do:
git reset [commit ID]
This will reset you back to that commit number, but your changes will still be there (meaning you'll be able to do more edits and git add them again later).
Once you have committed all of your changes, you should push the branch to the origin repository (your own fork on github):
git push origin [branch name]
This will push your changes to the branch of the same name on your own fork on github (branch will be created if it doesn't exist yet on github).
You need to issue a pull request from the branch on your own fork to Centinel's master branch. To do this, you can create a pull request on your own fork's github page.
If you need more information on pull requests, have a look here.
If you need more information about how to create a pull request, look here.
Important: These pull requests are subject to code review. During the code review process, you might need to add more commits to fix things or add more code. Remember that you don't need to issue a new pull request to do that. Just add more commits to your branch and git push them to your own fork. This will automatically update the pull request on the remote repository.
Once your code has gone through the code review and the reviewer's concerns and comments are all addressed, your pull request will be merged into the original repository.