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.

Feature Requests and Bug Reporting

• 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.

Branching

Contributors

• There are two branches in the main repo that will always exist - master and development.

  • master is the current stable release of Tonic. Most users will not go beyond this branch, so it's important to make sure things are pretty stable before merging here.
  • development is the workspace for features that are in-development or have not been fully tested yet. New feature branches should branch/merge from here.

• When the development branch is deemed to be stable on all supported platforms, it will be merged into master. All collaborators should be in agreement that the development branch is stable before it is merged to master.

• 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 master 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.

Forks

• Branches with changes for a specific project or application should not live in the main Tonic repo. Please fork Tonic to your own github account if you're modifying things for a particular use case.

• If you've made modifications that you feel will be useful in the main repo, please confine them to a branch in your fork and submit a pull request to the development branch in the main repo.

Merging and Pull Requests

• 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.

  • Rebasing is sometimes better for maintaining a cleaner commit history, but if you're having trouble or it doesn't make sense to rebase, just merge in changes from the parent instead. See links at the bottom of this page for more info.
    
    

• Once the branch has been merged or 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.

Uh-Oh

• 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.

Resources

Merging vs Rebasing
Rebasing Tips
Learn Git Branching
Pull Requests