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.
- Push changes ready for testing to
- Staging will get merged into
masterwhen it's stable
productionpulls from master
- 1 Overview Diagram
- 2 Branch Strategy
- 2.1 Main branches
- 2.2 Supporting branches
- 2.2.1 Beginning work on a new issue
- 2.2.2 Feature branches
- 2.2.3 Hotfixes
- 3 Note on Commit Messages
- 4 Development Timeline
- 5 Release Management
- 6 Links
We use branches to help with our release management, testing strategy, and helping with parallel development among the team.
WormBase/website repository, there are three main branches:
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
stagingbranch. This code gets pushed nightly to staging.wormbase.org.
production: the code currently in production. Branched off of
masterat each release.
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.
Beginning work on a new issue
Whenever you begin work on a new issue you should create a new branch for it.
git checkout -b my-new-issue staging
Now you can make your changes, commit some code. When you're ready, you can push your branch to your fork
git push origin my-new-issue
Continue making changes until your new code satisfies the following:
- Have written tests demonstrating the problem in the issue
- Pass the tests
- Complete the issue as much as possible without curators seeing an example
- Code style meeting the standards (indentation, comments, no debug statements)
When your code is ready, go to GitHub and create a Pull Request
- Go to the repository where you pushed your changes
- Switch to your branch (my-new-issue)
- Click the Compare & review button
- After reviewing all the changes, click on Create pull request in the header to send the pull request
- In the description, write a short summary of the issues and changes made along with some links for testing
Wait for another member of the web development team to review and merge your pull request. If more changes are requested, you can push more commits to the same branch and it will be added to the pull request.
Once your pull request is merged, locally bring in the changes and delete your issue branch
git checkout staging git pull git branch -d my-new-issue
Go to the original github issue:
- Add the Under testing label to your issue
- Comment on the issue to notify all involved that it is ready for testing. Add links for testing for the ease of testers.
- Another member of the WormBase group will close the issue once they have tested it
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
pushing directly to
If your change is small, and doesn't need a separate branch for development, you can push your changes directly to
Make sure that your code is:
- clean, formatted & commented
For all commits to
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
For a smaller changes on
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 (
squash), the SHA1 for the commit, and the commit message. By default, each commit has the
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
- Add the 'under testing' label to your issue
- Comment on the issue to notify all involved that it is ready for testing
- Wait for your issue to pass testing
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
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.
If a major bugfix is needed in production, create a hotfix branch from production. When finished, the branch needs to be merged back into
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
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
Link to an issue whenever a commit is related to that issue
fix #xxx will close the issue when this commit is pushed to master and notify that the issue will be closed .
The following synonyms are supported:
fixes #xxx fixed #xxx fix #xxx closes #xxx close #xxx closed #xxx
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