-
Notifications
You must be signed in to change notification settings - Fork 28
Development Workflow
Objective: This document intends to outline in writing the workflow for codius development. This provides a framework for us to ensure that code quality is improved, the master branch is always ready for a release, and development is monotonically pushed forwards.
Definitions:
- Code quality
- An objective metric derived from reviews of code that relates to good design, tight security, maintainability, reliability, and clarity.
- Release
- A map of version number to git commit
- Monotonically progressing development
- Test coverage ratio never goes down, burn rate is predictable, deadlines and goals are consistently met
Development of Codius happens in a sequence of rapid iterations based on epics, features, bugfixes, and releases.
Epics are collections of features and bugs. They are described in tracker as epics and have a broad description such as “Payments through bitcoin”
Features are discrete chunks of functionality in Codius. Using the above bitcoin payment example epic, a set of stories for that could be “monitor bitcoin network for payments”, “credit contract balance when bitcoin payment received”, “include bitcoin payment URIs in quote response”, etc. Bugs are defects in codius’ code that may be reported through github issues, jira tickets, random emails, or spontaneously added to tracker by contributors. Features and bugs are both tracked through their respective story types in Tracker.
Features and Bugs have the following states in Tracker:
- Unstarted - The story is not under active development
- Started - The story is under active development. It is associated with a specific pull request in the github repository. Multiple stories can be associated with a specific pull request. Pull requests should be linked to in the description of a story.
- Finished - The story is completed, though not yet ready for integration with the master branch
- Delivered - The story has been merged into the master branch
- Accepted - The story has made it into a release.
Stories may only be merged into the master branch on the following conditions:
- Test coverage does not decrease as a result of the merge
- New features contain new tests
- Bug fixes contain tests that can prove that a bug has been fixed
- Build infrastructure reports that the branch builds successfully, all tests pass, and there are no issues with any linters or static analysis tools
- There has been at least 1 “LGTM +1” from another core Codius contributor who has reviewed the code with an eye for security, reliability, maintainability, clarity, and other goals mentioned at the beginning of this document
To assist Codius developers with this, a robot will help by automating most of this procedure. The robot removes most human sources of error and reduces defect introduction vectors to a bare minimum: the code review process. To assist the robot in reading our minds, the robot needs some useful information embedded in commit messages. A regular expression of the form /\\[(Fixes|Finishes|Closes):? \#[0-9]+\\]/ is used to map specific commits to tracker story IDs. When a pull request is ready for a review, a string that matches the regular expression /\^+r\$/s is included in a comment. This notifies the bot through the normal github notification API, who then reviews a pull request to ensure that it passes the conditions to merge. If all conditions are met, the branch is merged and the pull request is closed.
The robot also updates Tracker tickets according to the above workflow. This removes the burden of keeping up with repetitive administrivia from contributors while maintaining consistent quality. A QA dashboard is available at http://build.codius.org/, which provides a map of stories to branches/pull requests, release deployment progress, build results, etc.
When a github issue is created, the robot should also create a tracker story that links to the github issue.
Codius is composed of multiple distinct packages that must work together to produce consistent and predictable behavior. As such, individual packages should rely on specific version numbers as much as possible to minimize the effects of API drift.
A release of Codius is considered to be a specific version of the “codius” NPM package on npmjs.org. Through this meta-package, we may reference a dependency tree of specific codius package versions. As such, a release of Codius may also be referred to as a mapping of a version number to a tuple of (codius-engine version, codius-sandbox version, codius-sandbox-core version, …).
Releases are tracked in git repositories via git tags that are gpg signed by whichever team member makes the release. Once a release is ready, it is deployed on the codius.host staging environment on our AWS elastic beanstalk setup.
There should be two stages to a full codius release: a number of release candidates, and a final release. Release candidates are tagged and sent to staging where bugs are discovered and fixed. Once a suitable number of release candidates have passed muster, the final release is tagged and sent to staging for deployment to npm, codius.host production, partners, etc.
Once a full release (not a release candidate) is tagged and sent to staging, the associated stories in Tracker are marked as accepted by walking the git history of the tag and extracting tracker story IDs.
- frog hop - technicalities: "not rocket science" (the story of monotone and bors): http://graydon.livejournal.com/186550.html