GitHub Workflow
This page is intended to provide standard procedures for how we use Github for both version control and for documentation. Please refer to the diagram and the descriptions below.
The README should provide a high level description of the current state of the project plus installation instructions.
The Wiki is for documentation of any depth that isn't directly tied to the code. It should reflect the current state of things rather than attempting to provide a history. Relative to comments in the code, this is the level of the forest.
These should provide specific context and why to help make the code more understandable to later devs. These should reflect the current state and are at the level of the trees.
The development process starts with an issue. Github recommends that issues be used for "ideas, enhancements, tasks, or bugs." We use them for discussion and tracking overall progress but not for documenting code-level changes.
At this point, someone (the dev) decides to take an issue and begin to work with it at the code level. The dev will start by pulling the current Master into a local feature branch on their development machine. In that process he/she will populate a local work directory with the files pulled from the current Master.
As the dev works on the code, he/she should make frequent commits to the local feature branch reflecting small changes. Commit messages should be short but meaningful.
Once the code is far enough along that the dev would like to
- get feedback from others
- provide history documentation at a higher level than the commit messages and/or
- backup the work on Github the dev will push the code from the local feature branch to Github thereby creating a feature branch.
This is also a good time to create a pull request as a place to house the higher-level discussion that is nevertheless tied directly to the feature branch. At this point, the discussion moves from the issue to the pull request. Think of the pull request as providing the primary documentation about that branch.
The dev continues to work on the code, making frequent commits to the local feature branch. He/she makes less frequent pushes to the Github feature branch when there are important milestones or when the dev wants more feedback/discussion and therefore needs to provide others with the most up-to-date version of the code.
At some point the dev decides the code is ready so makes a (hopefully) last push.
If all goes well, the code passes final review and tests. At this point
- the code can be merged back into the Master branch
- final comments can be made in the pull request and it can be closed
- the issue can also be closed with whatever final comments are appropriate.