-
Notifications
You must be signed in to change notification settings - Fork 63
Collaboration and Version Control Guidelines
Welcome! Here you will find a list of VCS guidelines for making the best use of git and github for contributing to Tonic. Although these guidelines are not strictly binding, please attempt to follow them as closely as possible in order to make merging, issue reporting, and the entire development process go as smoothly as possible.
-
Please open a github issue for every feature request, bug, or any other changes/additions that are intended to be applied the master codebase.
-
If you begin working on an issue, whether existing or newly created, assign it to yourself. This allows other collaborators to see what you're working on so nobody ends up working on the same thing at the same time, and creates a persistent log of features and bugs that lives with the project source code itself.
-
When committing code that pertains specifically to an issue, it's useful to include the issue number as part of the commit message. For example, if you're working on issue #24, your commit message might look like
git commit -m "Did something to the code. #24"
This will cause the commit to show up in the comment/status history for that issue, allowing other collaborators to see what code changes pertain to the issue. Be aware that adding "fixes" or "closes" before the issue number in the commit message will also close the issue, which in some cases can be a convenient shortcut.
-
A new branch should be created for working on features, bug fixes, or any other code that is intended to eventually be merged into the codebase. DO NOT push commits directly into an existing branch.
-
Feel free to push your branch to the remote repo, but be sure the name you give the branch is prefixed with your initials and clearly and succinctly defines why it was created (e.g.
ND-ControlValueFix). This allows other collaborators to clearly identify who "owns" the branch and easily distinguishes feature/bugfix branches from long-term version, development or experimental branches, which will not have prefixes. -
In order to keep the branch space clean, once your branch is no longer necessary, please delete it from the remote repo. If you open a pull request, don't be surprised if the maintainer deletes the branch after merging it.
-
Once your branch is ready to merge back to its parent, be sure to merge or rebase in order to ensure that your branch is up-to-date with any commits that may have been added to the parent and can be automatically merged by GitHub.
-
Once the branch has been rebased, submit a GitHub pull request so that another collaborator can review your changes and accept or decline the merge. Please provide any information that you think another collaborator may find useful in the pull request comments, including whether the branch can be deleted once the pull request is accepted.
-
While multiple pull requests from the same branch are possible, it is discouraged in favor of creating a different branch for each set of fixes. This keeps the commit and branch log a bit easier to follow, since each branch will have a contiguous lifecycle.
-
If you happen to make a mistake while merging, rebasing, or taking other git actions and the commit history becomes corrupted, please do not push to the remote repo and NEVER force-push unless you have a very good reason, such as updating the remote repo after a successful rebase.
-
Git has advanced data recovery features that can help recover your changes if things go awry. If ever in doubt, always contact another collaborator and ask for assistance.
Merging vs Rebasing
Rebasing Tips
Learn Git Branching
Pull Requests