-
Notifications
You must be signed in to change notification settings - Fork 3
Rights app development process
This document describes how the rights-app software is created. It is based on the development process documentation text by the lobid team. (Thanks to @fsteeg who wrote most of the lobid version.)
The software is developed on GitHub. Not just the results of the development process are published on GitHub, but instead the actual development (track issues, change code, discuss changes) happens here – open for anybody to follow.
A modified version of the GitHub workflow is used:
- the master branch is always in a deployable state.
- New features are developed in feature branches, which are merged into the development branch using pull requests with a first review within the development team. ** The development branch is merged into the master branch using pull requests reviewed by the International Rights Statements Working Group.
See details on the GitHub flow.
GitHub issues are used to keep track of requirements, open questions and bugs.
For tracking the development progress and getting an overview over the state of all issues a board is used at https://waffle.io/rightsstatements/rights-app.
The columns of the board correspond the subsequent stages of the development process, from left to right:
Backlog -> Ready -> Working -> Review -> Done
Columns correspond to a specific label on GitHub issues, i.e. moving a card from working to review is the same as removing the working label and adding the review label in GitHub. Issues without a label are located in the backlog column.
The backlog contains all planned issues and open questions.
An item is ready if it’s possible to start working on it, i.e. there are no blocking dependencies and requirements are clear enough to start working. Prioritized items are moved to the top of the ready column.
Felix does the coding. When he starts working on an issue, he moves it to the working column.
Felix pushes the commits corresponding to the issues he works on to a feature branch that is named after the features it adds, e.g. dereference-vocab. He then deploys the changes from the feature branch to the staging system.
Felix opens a pull request to merge the feature branch into the development branch with a summary of the
changes, and associating the corresponding issues with keywords like "Fixes #123.", and instructions on how to
test the behaviour on staging. The pull request and associated issues are automatically moved to the review column. Felix assigns the pull request to Adrian who does the functional review.
Adrian reviews the feature based on the provided instructions, and provides feedback on the functionality. If something has to be adjusted, Felix changes the code in additional commits, which he pushes to the feature branch. They are added to the existing pull request automatically. See details on pull requests. At the end of the review, Adrian posts a +1 comment and assigns it to Felix who merges the commits into the development branch. This process may be repeated several times before a pull request against the master is made.
As soon as sufficient progress has been made so that review by the International Rights Statements Working Group makes sense, Felix does a pull request to merge the development branch into the master and assigns this pull request to Mark. The same review process as above repeats with Mark and other members of the International Rights Statements Working Group as reviewers. As soon as the desired functionality is there, the development branch is merged into master.
Travis CI is used for continuous integration. The CI is integrated into the GitHub review process: when a pull request is opened, Travis builds the resulting merged code and provides feedback right in the pull request (you can see the build status in the pull request preview, before submitting the pull request). For details, see this post. The developer who pushed the code should ensure the Travis build was successful before submitting the pull request for review.
When the changes are merged into the master branch, the corresponding issues are automatically closed
in GitHub and moved to the done column in the board.
to be added
Git commits should be as granular as possible. When working on a fix for issue X, Felix does not add other things he notices (typos, formatting, refactorings, etc.) to the same commit.
Felix follows the established conventions for Git commit messages:
imperative mood (e.g. Fix UI issue, not Fixes UI issue), short lines
(max 72 chars), and either just one line, or one line, a blank line, and
one or more paragraphs. For details, see
these
posts.
Every commit should be related to a GitHub issue. This allows to
understand why certain changes were applied. It’s enough to just mention the issue
number with a prefixed # mark, e.g. Fixes #111).