How do we use GitHub and Git?

Issue Tracking - GitHub Issues

General Usage

• We use GitHub issues for issue tracking
• To track sizings and priority we use labels associated with issues. For sizings we label issues with size X (X being the size) and for priority low-priority, medium-priority & high-priority.
• To track issues relating to a high level feature, or area of the code base we also use tags, e.g. bundlers and/or core for bundler related issues.
• Issues should either be features, bugs, or improvements. We should try not to split features up in to too many smaller issues since it makes it difficult to track when the feature is done (people may watch a single issue).
• If features are small enough we use the same issue as a tech task that needs to be done
• If features are much larger we split it into several tech tasks and add the list of sub-issues to the parent’s description.
• Labels are also use to identify issues that aren’t valid, feature requests, bugs etc.

Sprint Board

• We use Huboard as a sprint board. This uses metadata on issues to work out what column things should be in.
• The labels starting with X - (e.g. 2 - Dev) are all labels for Huboard columns.

Issues

• Issues in the current 'sprint' should be assigned the 1 - Planned, all other issues that are not currently being worked on should be labeled 0 - Backlog (the backlog label is optional since Huboard displays all unlabled issues in the backlog anyway)
• The various other labels can be used to detirmine the status of the issue during the current sprint.
• Issues do not need dev reviwing since all code goes into the codebase via pull requests which are dev reviewed, the lifecyle of an issue is:
  • raised (backlog) -> planned -> dev -> ready for test -> test -> done

Pull Requests

• Pull requests should be raised for any new code
• The description to give a high level overview of the changes (even if the commits and/or issue detail this) with a link to any relevant issues
• The lifecyle of a pull request is:
  • raised -> dev review -> ready for test -> test -> done

Milestones

• Milestones represent both sprints and when features are complete - we should try to complete a feature in a sprint, if we can’t its probably too big and should be broken down.
• For whatever reason, if an issue isn’t completed in the milestone we move the issue to the next milestone and change the description of each milestone to reflect the change of delivery date for the issues.
• Any issue that isn't in a sprint goes on to the backlog - and doesn’t go into a milestone.
• The milestone view then gives us an up-to-date roadmap with approximate completion dates for each feature.

Feature Requests/Bugs

• These get raised and tagged like any other issue.
• By default they go into the backlog (no milestone assigned) until they are triaged.

Wiki

• We use the GitHub Wiki for the bladerunnerjs/brjs repo for notes, design discussions and other things that we need to capture long term that might be useful for other people and contributors.

Git Workflow

Branching

The below is an adaptation from the Git Flow model, but made slightly more similar to GitHub’s workflow. This video also has some interesting stuff about working with Git.

Branch	Notes
master	- The stable branch - This is where we release from - No one should commit here, only merge features branches in to it
feature-X	- A branch off of the master branch to develop a particular feature or fix

Pull Requests

Core Team

• Pull requests should be made for feature branches -> master
• This is where we can then add release notes, capture any notes related to the merge etc.

External Pull Requests

• These should be merged in to master and tied in to a release as with any other feature

Versioning & Releasing

• The version is calculated using the Git command ‘git describe --tags --long’ (more info here)
• This results in a version that looks like: --
• The build will automagically do this and the version will be calculated the same on a dev machine as in CI.
• To release:
• We tag the current commit with a tag to represent the version (e.g. 0.1).
• When any build is run, the version is calculated as 0.1-0-abcdefg
• If anyone checks in to the branch without creating a new tag (e.g. for a minor release note change) - the version becomes 0.1-1-xyzabc.
• We can then, optionally, upload a binary in GitHub and add release notes in GitHub’s Releases section.

CI

• We will have CI builds set up for master
• CI will not run for feature branches, unless we know its going to be a relatively long lived branch with alot of people working on the branch.

Other Workflow Notes

• Development of each feature should be performed in a feature branch on the developers machine.
• Long lived (> 3 hours) local feature branches should be pushed
• Regular commits to the local feature branch can be made as necessary.
• The final commit-and-push can be marked with the name of a developer that can perform code review (e.g. @dchambers), causing them to receive an email.
• The reviewer will either ask the developer to make some changes before accepting the commit, or will signal their acceptance of the commit by doing a pull-request through github.
• The QA will listen out for pull-requests, and can provide assurance of each change (e.g. that it has decent test coverage, passes all existing automated tests and passes manual testing).
• The QA will merge the request and delete the feature branch if they are happy with the quality of the commit.
• QAs should not process external pull requests, as these will be dealt with separately by the tech lead.