Development Process Overview - IntegratedBreedingPlatform/Documentation GitHub Wiki

As of September 1, 2015, Leafnode development team adopted "branch-per-task" and "Pull Request" model. The workflow is very similar to the standard GitHub Flow.

Code is only merged into the master branch after rigorous in-branch testing and code reviews which includes code design, logic, maintainability, performance considerations, coding standards, unit and integration test coverage review. This model allows us to offset rework, address technical debt in the product and provide training by example in the art of reviewing code to each other. In-branch testing is facilitated by Jenkins build system utilizing the Jenkin's Groovy and Shell script based workflow system also known as Build Pipelines.

Please read through general principles of development and review, and take care to follow the steps outlined in order to submit code to reviewers for ultimate merge to the master branch.

Core Principles

  • We use Git as our source control system.
  • Our workflow is primarily a feature branch workflow based on a central repository hosted at GitHub.
  • Everyone clones from the central repository and works locally.
  • No work is pushed directly to the master branch. Work is indcluded into the master branch via branch & pull-request review system.
  • Everyone synchronizes their work back to the central repository by creating a pull request when all items on the Development Done Checklist are satisfied and the work is ready to be reviewed via pull-request for merge into master.
  • Everyone keeps their working branch synchronized with master by merging master into their working branch.
  • The master branch on the central repository should at all times be in a state ready to compile, build, pass the tests, package, deploy and potentially release.
  • Keep the history on the central repository clean and readable. Master branch must represent the official history of changes clearly.
  • Commits must be small and atomic i.e. relate to one and only one clear logical reason for change.
  • Avoid big bang massive commits with lots of modifications. Breakdown bigger tasks into sub tasks such that each sub task can be completed with a small amount of changes in one small commit.
  • Commit messages must summarise the changes made and the reasons/intent clearly so that anyone pulling it or looking at history can easily understand why the changes were made.
  • No commits should be made without an JIRA ticket number for reference. If an issue does not exist, create one describing the reason why change is needed.
  • No commits should be made without name of a code reviewer. No commits should be made prior to the review i.e. no post-commit reviews.
  • Creating a branch per issue or per feature is required.
  • Use meaningful and consist format branch names e.g. BMS-123-Keyword where keyword is an easily understood indicator of the work.
  • To keep the history clean and readable, use rebase instead of merge as much as possible (when your branch is still local and has not been pushed) when pulling work from central repository. Rebasing must NOT be done on branches once they are pushed. --> See the Perils of Rebasing and a pretty good StackOverflow explanation
  • Avoid auto merges
  • Tags for releases should follow a consistent naming convention. Use the version number of software branch rather than date stamps.
  • When pushing to the central repository, ensure there is nothing that is specific to your local copy that gets pushed. Discard all local/temporary branches/tags etc.

Steps to follow

  • Ensure there is a JIRA ticket for the work you are about to begin. Lets say the ticket is BMS-123.
  • Create a branch with an appropriate name e.g. BMS-123-Keyword where keyword is an easily understood indicator of the work.
  • Commit atomic units of work in your branch with clear and conscise commit messages.
  • Push your branch to the remote repository.
  • When all the work is complete and is ready for branch testing the Definition of Done checklist, utilise the Jenkins pipeline deploy system to deploy your branch code for QA to test.
  • Once in-branch testing is done and any issues reported are addressed in branch create a pull-request.
  • Pull request will be reviewed by Team NZ, review comments will be provided.
  • If there are changes to be made as a result of the review, make them in the same branch and push them. Your changes will become part of the existing pull request (no need to create a new pull request). Comment on the pull request that this has been done so that the reviewer can see them.
  • Reviewer will merge the pull request into master once all changes have been satisfactorily reviewed and accepted.

Write good commit messages

Rules of a great git commit message

  • Separate subject from body with a blank line
  • Limit the subject line to 50 characters
  • Capitalize the subject line
  • Do not end the subject line with a period
  • Wrap the body at 72 characters
  • Use the body to explain what and why rather than how
Summarise changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequenses of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Issue: BMS-1384
Reviewer: Developer Name

References