Skip to content
This repository has been archived by the owner on Dec 12, 2018. It is now read-only.

Development Process Explained

Jump to bottom
mrioan edited this page Nov 2, 2016 · 15 revisions

Background

Stormpath uses a number of the built-in features of Github as well as waffle.io to manage our development process internally. Our repo, and thus all our issues and pull requests are public. Our waffle.io page is public as well, which makes it easy to see what's in the hopper for development and who is working on what.

The rest of this page outlines the basic rules we follow to get from the backlog to done and release.

The Flow

Here's the flow of issues through the process:

backlog -> milestone -> ready -> in progress -> needs review -> done

  1. An issue gets into the backlog simply by virtue of it being defined in github.

  2. A milestone defines a unit of work to be released. All issues assigned to the milestone will be included in the release.

  3. Once a milestone is defined and issues added to it, the ready label can be applied. This indicates that these issues are ready to be worked on. Note: there should only ever be issues in the same milestone with the ready label.

  4. A developer can "pick up" an issue to work on by applying the in progress label to it. Any issue with the in progress label should also have a developer assigned to it.

  5. When an issue is ready to be reviewed, the developer who worked on it should create a Pull Request (PR) for it. The title or the description of the PR should reference the issue number with the pound sign (#) in front of it (description example: resolves #444). The issue should have the in progress label removed and the needs review label applied.

Note: There should be no more than 3 issues with the needs review label applied. If you are ready to have an issue reviewed and there are already 3 issues with the needs review label applied, you should pick up one of those issue by assigning the associated PR to yourself. If all three issues are already assigned, then you should see which issue you can 'dogpile' on to get it reviewed and approved sooner.

  1. Any developer, other than the one who worked on the issue, can "pick up" the PR and become the reviewer. This is done by the reviewer assigning the PR to themselves. If there is feedback on the PR, the reviewer will assign it back to the developer for update. Once the developer has addressed the comments from the reviewer, the developer will assign the PR back to the reviewer. This continues until the reviewer approves the PR and assigns it back to the developer a final time.

  2. Once a reviewer has approved a PR and assigned it back to the developer, AND the CI build is successful, the developer will merge the PR, close the issue and delete the branch. This will automatically remove the "needs review" label. Note: If the last commit message includes one of the keywords that Github uses for automatic closure and references the issue, the issue will be closed automatically.

Waffle.io and the Flow

Working with the labels as described in the previous section, will automatically cause the issues to flow through the waffle.io columns.

Alternatively, developers can work directly in waffle.io. Dragging an issue from the Ready column to the In Progress column automatically removes the ready label and applies the in progress label to the issue in Github.

There are two things that github.com has the waffle.io does not yet:

  1. The results of the CI build (travis)
  2. The milestone view, which shows % complete

Ready

[![ready][1]][1] [1]: images/dev_process/ready.png

In Progress

[![in progress][2]][2] [2]: images/dev_process/in_progress.png

Needs Review

[![needs review][3]][3] [3]: images/dev_process/needs_review.png

Summary of The Rules

  1. We follow a roughly Kanban approach. This means that the right most columns take precedence over the ones further to the left. If you are ready to pick up new work, you should first check to see if there are any issues with the needs review label applied. If so, then look at the associated PR and assign it to yourself if not already assigned.

  2. All issues with the ready label applied should have a milestone assigned AND it should be the same milestone.

  3. Only issues with the current milestone should ever have the in progress label applied.

  4. Any issue with the in progress label applied should have a developer assigned.

  5. When the assigned developer completes work on an issue, that developer will:

  6. create a pull request (PR) that references the issue number in the title or description

  7. remove the in progress label from the issue

  8. apply the needs review label to the issue

  9. Another developer will assign themselves to the PR, thus becoming the reviewer.

  10. If the reviewer has comments/requests on the PR, the reviewer assigns the PR back to the `developer

  11. When the developer resolves the comments from the reviewer, the developer assigns the PR back to the reviewer

  12. repeat 1 and 2 as needed

  13. The reviewer adds a comment to the PR indicating that it is approved and assigns the PR to the developer

  14. The developer merges the PR, closes the issue and deletes the github branch/

Appendix A

Checklist for Implementers and Reviewers

An issue should only be considered ready to be reviewed if all the following requirements are met:

  1. Javadoc: All new classes and methods in the API module have complete and detailed javadocs. For those in other modules (servlet, spring, impl, etc) we should add documentation for complex algorithms/behaviors/cases. New classes and methods must contain the @since tag (e.g @since 1.0.RC9)

  2. Testing: Make sure there are tests (ITs preferably) that verify most (if not all) the possible flows of the new functionality

  3. Copyright: New files have the Copyright header

  4. Imports: Check there are no unused imports

  5. Pre-existent References: Do a deep search for the exact github issue that you are working on right now. For example if you are working on issue 502 then do do a search within our project with the text https://github.com/stormpath/stormpath-sdk-java/issues/502. There might be some pieces of code referencing it for some reason and we need to be sure that we are addressing those comments as well. For example, there might be a test that is disabled waiting for a particular issue to be solved. If that is the case then this test should be enabled as part of the implementation of 502.

  6. Add Comment Referencing Issue: If a bug fix has a localized implementation (like a few lines of code inside and if statement) make sure to add a reference the issue that originated that change. For instance, //This fixes https://github.com/stormpath/stormpath-sdk-java/issues/XXX

  7. CI: Make sure Travis passes

  8. UAT: The implementer describes the specific things the reviewer needs to validate. If steps are complex then the implementer should also add instructions for the reviewer.

  9. TCK: The implementer must clarify in the PR which are the specific TCK tests that are supposed to succeed in this particular feature.

  10. Documentation: If the PR is for a new feature there must always be documentation about it in our Product Guide. If the documentation has not yet been written then at least there must be an issue in Github in order to remember to do so soon. IMPORTANT NOTE: The documentation must never be released before the actual feature.

Appendix B

Semantic Versioning

In short this is the way we handle code changes during specific versions:

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes
  2. MINOR version when you add functionality/new features in a backwards-compatible manner
  3. PATCH version when you make backwards-compatible bug fixes ( ie. I can downgrade from 1.0.9 to 1.0.3 without changing any of my code)

We always stick to this versioning scheme and by no means we will relax it.

See http://semver.org/ for a more detailed explanation.

Clone this wiki locally