Development workflow - webdev

This page describes the development model used by the web development team at WormBase using git as our version control system. This includes our branching strategy and release management.

1. Push changes ready for testing to staging
2. Staging will get merged into master when it's stable
3. production pulls from master

Overview Diagram

Editable version of the diagram

Branch Strategy

We use branches to help with our release management, testing strategy, and helping with parallel development among the team.

Main branches

Inside the WormBase/website repository, there are three main branches: master, staging and production.

• master: current, stable code. All new changes brought into master have been tested on staging.wormbase.org and approved by either the curator requesting the change, or the development lead.

• staging: any features/changes ready for testing should be pushed to the staging branch. This code gets pushed nightly to staging.wormbase.org.

• production: the code currently in production. Branched off of master at each release.

Supporting branches

Other types of branches used can include feature branches and hotfixes. These branches are only intended to live until the new feature is merged into dev or the fix is completed.

Feature branches

Any new major features should branch off staging. Once the feature is ready for testing, it can be merged back into staging. These aren't necessarily branches in the main repository - can be local, or on a developer's fork.

Starting a feature

Create a branch from staging for your work on this feature/issue/bug

git checkout -b myFeature staging

Finishing a feature (ready for testing)

When you're ready to incorporate your feature and have it tested on staging.wormbase.org, you can push your changes to staging

pushing directly to staging

If your change is small, and doesn't need a separate branch for development, you can push your changes directly to staging.

Make sure that your code is:

• clean, formatted & commented
• stable

For all commits to staging

Keep your commit message as descriptive as possible, reference any issues affected, close any this resolves:

This is a summary of my commit.
* here is a breakdown of the different changes
* mention github users (@tharris) when appropriate
* related to #YYY
* fix #XXX

merging your branch to staging

For a smaller changes on myFeature branch:

git checkout staging
git merge --squash myFeature
git commit -v 
#follow commit message guidelines from above here

Insert a commit message at this point. You can use --squash to remove any checkpoint commits you may have added to your branch during development, ie. you may have committed debug statements, or broken changes you have since removed. Make sure you update the issue so it can move into testing.

If your feature is larger and would benefit from having the work broken down into several commits, you can rebase instead:

git checkout myFeature 
git rebase --interactive staging

This will open your editor with a list of commits. Each line has the operation to perform (pick or squash), the SHA1 for the commit, and the commit message. By default, each commit has the pick operation:

pick 8af9b68 Update search
pick c180b1b bug fix
pick 36afac4 work on field titles

Changing the operation to squash will squash that commit.

pick 8af9b68 Update search
squash c180b1b bug fix
pick 36afac4 work on field titles

When you save and close the editor, a new editor will pop up for a commit message for the combined commit. Follow the commit guidelines here, including closing/referencing issues.

Now, comment on the github issue to notify all parties involved that the feature will be ready for testing on staging soon.

after merging to staging

1. Add the 'under testing' label to your issue
2. Comment on the issue to notify all involved that it is ready for testing
3. Wait for your issue to pass testing

Testing issues

All issues need to be tested and closed by at least one person who is not the developer who made the change. Ideally, it would be the curator asking for the feature/fix.

If you would like to help test:

• Look at the open issues 'under testing'.
• All the changes for these issues are available for testing on staging.wormbase.org.

If you are not the developer who pushed the code for this issue:

• You can test out the changes and leave any feedback you have in the issue comments.
• If you think this feature/fix is ready for production, you can remove the 'under testing' label, or close the issue.

Moving a feature to master (pass testing)

First, check to see which issues are currently being tested: open issues 'under testing'

If this list is empty, staging can be merged onto the master.

In github, create a pull request for staging. Look at the Commits and Files changes. In the comment, summary all the features/issues introduced and make sure they are stable. Click on send pull request.

Once the pull request is reviewed, it can be merged into the master branch.

Hotfixes

If a major bugfix is needed in production, create a hotfix branch from production. When finished, the branch needs to be merged back into production and staging

Begining a fix

git checkout -b hotfix-issXXX production

Fix the bug and commit the fix in one or more commits. Reference the github issue:

git commit -m "Severe production bug
* search redirecting to home page
* fix #XXX"

Closing the fix

The fix needs to be merged back to both production and staging

git checkout staging
git merge hotfix-issXXX

git checkout production
git merge hotfix-issXXX

Note on Commit Messages

Here is a template originally written by Tim Pope at tpope.net:

Short (50 chars or less) summary of changes

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 an email 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); tools like rebase can get confused if you run the
two together.

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

issues and commits

issues 2.0 the next generation

Link to an issue whenever a commit is related to that issue #xxx.

Using fix #xxx will close the issue when this commit is pushed to master and notify that the issue will be closed [1]. The following synonyms are supported:

fixes #xxx
fixed #xxx
fix #xxx
closes #xxx
close #xxx
closed #xxx

Development Timeline

See: WormBase Release Workflow

Release Management

When production is ready to updated for release WSXXX:

Create a new pull request from master to production. Review all changes going into new release. Merge in the pull request. Tag production branch with appropriate release name.

git checkout production
git tag -a WSXXX

Links

• staging site for testing
• github repository
• github issue tracker
• workflow diagram