Difference between revisions of "Development workflow - webdev"

From WormBaseWiki
Jump to navigationJump to search
 
(60 intermediate revisions by one other user not shown)
Line 1: Line 1:
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.
+
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. We use git and GitHub to help us manage development.
 
 
# Push changes ready for testing to <code>staging</code>
 
# Staging will get merged into <code>master</code> when it's stable
 
# <code>production</code> pulls from master
 
 
 
  
 
= Overview Diagram =
 
= Overview Diagram =
Line 11: Line 6:
 
[https://docs.google.com/drawings/d/1j-a-8a_hTIqCiMCRLUcemGqEe_c8LXOZKuioHlE9oX4/edit?usp=sharing Editable version of the diagram]
 
[https://docs.google.com/drawings/d/1j-a-8a_hTIqCiMCRLUcemGqEe_c8LXOZKuioHlE9oX4/edit?usp=sharing Editable version of the diagram]
  
= Branch Strategy =
+
= Contributing =
We use branches to help with our release management, testing strategy, and helping with parallel development among the team.
 
 
 
== Main branches ==
 
Inside the <code>WormBase/website</code> repository, there are three main branches: <code>master</code>, <code>staging</code> and <code>production</code>.
 
  
* <code>master</code>: current, stable code. All new changes brought into master have been tested on [http://staging.wormbase.org staging.wormbase.org] and approved by either the curator requesting the change, or the development lead.
+
Whenever you begin work on a new issue you should create a new branch for it. Any new features should branch off <code>staging</code>. Once the feature is ready for testing, you can submit a pull request to <code>staging</code> for code review. Feature branches aren't necessarily branches in the main repository - they can in the main WormBase repository, or on a developer's fork. [http://wiki.wormbase.org/index.php/Development_workflow_-_webdev#Branch_stratgey Read more on our branching strategy]
 
 
* <code>staging</code>: any features/changes ready for testing should be pushed to the <code>staging</code> branch. This code gets pushed nightly to [http://staging.wormbase.org staging.wormbase.org].
 
 
 
* <code>production</code>: the code currently in production. Branched off of <code>master</code> 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 <code>dev</code> or the fix is completed.
 
 
 
 
 
=== Making changes ===
 
 
 
Whenever you begin work on a new issue you should create a new branch for it.
 
  
 
  git checkout -b myFeature staging
 
  git checkout -b myFeature staging
  
Now you can make your changes, commit some code. [http://wiki.wormbase.org/index.php/Development_workflow_-_webdev#Note_on_Commit_Messages Note on commit messages]
+
Now you can make your changes and commit some code. [http://wiki.wormbase.org/index.php/Development_workflow_-_webdev#Commit_messages Read more on commit messages]
 +
git add /PATH/TO/UPDATED/FILE
 +
git commit -m "Descriptive commit message"
  
Keep your commit message as descriptive as possible, reference any issues affected, close any this resolves:
+
When you're ready, you can push your branch to GitHub
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
 
 
 
When you're ready, you can push your branch to your fork
 
  
 
  git push origin myFeature
 
  git push origin myFeature
  
Continue making changes until your new code satisfies the following:
+
Continue making changes until your code is ready for a code review. [http://wiki.wormbase.org/index.php/Development_workflow_-_webdev#Is_my_code_ready_for_review.3F Is my code ready for review?]
 
 
* 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. [http://nathanhoad.net/git-workflow-forks-remotes-and-pull-requests More info on Pull Requests.]
 
When your code is ready, go to GitHub and create a Pull Request. [http://nathanhoad.net/git-workflow-forks-remotes-and-pull-requests More info on Pull Requests.]
  
 
# Go to the repository where you pushed your changes
 
# Go to the repository where you pushed your changes
# Switch to your branch (myFeature)
+
# Using the drop down, switch to your branch (e.g. myFeature)
 
# Click the green '''Compare & review''' button
 
# Click the green '''Compare & review''' button
 
# After reviewing all the changes, click on '''Create pull request''' in the header to send the pull request
 
# 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
+
# In the description, write a short summary of the issues (along with a link to the issue) and changes made along with some links for testing  
 +
#* [http://wiki.wormbase.org/index.php/Development_workflow_-_webdev#What_info_should_I_include_in_a_Pull_Request.3F What info should I include in a Pull Request?]
  
 
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.
 
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.
Line 73: Line 43:
 
# Another member of the WormBase group will close the issue once they have tested it
 
# Another member of the WormBase group will close the issue once they have tested it
  
=== Feature branches ===
+
Note: You can view all merged pull requests using this link: https://github.com/WormBase/website/pulls?q=is%3Apr+is%3Amerged
Any new major features should branch off <code>staging</code>. Once the feature is ready for testing, it can be merged back into <code>staging</code>. These aren't necessarily branches in the main repository - can be local, or on a developer's fork.
+
== Is my code ready for review? ==
  
==== Starting a feature ====
+
Before you send a Pull Request, please make sure you have completed the following:
Create a branch from <code>staging</code> for your work on this feature/issue/bug
 
git checkout -b myFeature staging
 
  
 +
* Written tests (API tests or REST tests) demonstrating the problem in the issue. [http://wiki.wormbase.org/index.php/Unit_Testing More info on testing]
 +
* Fix the problem (ie pass the tests)
 +
* Complete the issue as much as possible without curators seeing an example
 +
* Code style meeting the [http://wiki.wormbase.org/index.php/Coding_standards WormBase coding standards] (indentation, comments, no debug statements)
  
 +
== What info should I include in a Pull Request? ==
  
==== Testing issues ====
+
To help your reviewer understand your code, please try to include the following in the Pull Request description
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 [https://github.com/WormBase/website/issues?labels=under+testing&state=open open issues 'under testing'].
 
* All the changes for these issues are available for testing on [http://staging.wormbase.org 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 <code>master</code> (pass testing) ====
 
First, check to see which issues are currently being tested:
 
[https://github.com/WormBase/website/issues?labels=under+testing&state=open open issues 'under testing']
 
  
If this list is '''empty''', <code>staging</code> can be merged onto the <code>master</code>.
+
* A link to the issue being addressed
 +
* Short summary of the problem
 +
* Some links to use for testing
 +
* Any other information that may be needed to testing (ie wormbase_local.conf changes, extra files needed, etc)
  
In github, create a [https://github.com/WormBase/website/pull/new/staging 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'''.
+
== Commit messages ==
 +
git commit -m "COMMIT MESSAGE GOES HERE"
  
Once the pull request is reviewed, it can be merged into the master branch.
+
Keep your commit message as descriptive as possible, reference any issues affected by the issue number (#YYY):
 
+
This is a summary of my commit.
=== Hotfixes ===
+
* here is a breakdown of the different changes
If a major bugfix is needed in production, create a hotfix branch from production. When finished, the branch needs to be merged back into <code>production</code> and <code>staging</code>
+
  * mention github users (@tharris) when appropriate
 
+
  * related to #529
==== Begining a fix ====
+
  * #945
  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 <code>production</code> and <code>staging</code>
 
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:
 
Here is a template originally written by Tim Pope at tpope.net:
Line 143: Line 91:
 
</pre>
 
</pre>
  
== issues and commits ==
+
= Code Review =
[https://github.com/blog/831-issues-2-0-the-next-generation issues 2.0 the next generation]
 
  
Link to an issue whenever a commit is related to that issue <code>#xxx</code>.
+
All changes must go through a code review before being merged to the staging branch. At WormBase, this is done using Pull Requests. All members of the core development team are expected to keep an eye on the open Pull Requests and reviewing the ones they are assigned.
 +
 
 +
* Test out the pull request (check out the branch)
 +
* Take a quick look at the code (are there comments? anything obvious missing)
 +
* Run the tests written for this issue
 +
* Leave a comment on the PR if you notice anything that needs to be fixed
 +
* Merge the PR if you think it looks good
 +
** Begin by merging staging into the feature branch.
 +
** If there are conflicts, ask the owner of the PR to help resolve them.
 +
 
 +
= 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 [https://github.com/WormBase/website/issues?labels=under+testing&state=open open issues 'under testing'].
 +
* All the changes for these issues are available for testing on [http://staging.wormbase.org staging.wormbase.org].
 +
* 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, please '''close the issue'''.
 +
 
 +
= 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 <code>WormBase/website</code> repository, there are three main branches: <code>master</code>, <code>staging</code> and <code>production</code>.
 +
 
 +
* <code>master</code>: current, stable code. All new changes brought into master have been tested on [http://staging.wormbase.org staging.wormbase.org] and approved by either the curator requesting the change, or the development lead.
 +
 
 +
* <code>staging</code>: all changes get pushed to the <code>staging</code> branch after code review. This code gets pushed immediately to [http://staging.wormbase.org staging.wormbase.org].
 +
 
 +
* <code>production</code>: the code currently in production. Branched off of <code>master</code> at each release.
 +
 
 +
== Feature branches ==
 +
Any new features should branch off <code>staging</code>. Read more on feature branches in [http://wiki.wormbase.org/index.php/Development_workflow_-_webdev#Contributing our contribution guidelines]
 +
 
 +
== Hotfixes ==
 +
If a major bugfix is needed in production, create a hotfix branch from production. When finished, the branch needs to be merged (via PR/code review) back into <code>production</code> and <code>staging</code>
 +
 
 +
=== 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"
  
Using <code>fix #xxx</code> will close the issue when this commit is pushed to master and notify that the issue will be closed [https://github.com/blog/1386-closing-issues-via-commit-messages].
+
=== Closing the fix ===
The following synonyms are supported:
+
To close the fix, send a Pull Request to both the <code>production</code> and <code>staging</code> for code review. The reviewer will merge the branch.
fixes #xxx
 
fixed #xxx
 
fix #xxx
 
closes #xxx
 
close #xxx
 
closed #xxx
 
  
 
= Development Timeline =
 
= Development Timeline =
  
See: [[WormBase_Release_Workflow|WormBase Release Workflow]]
+
See: [https://docs.google.com/document/d/1zIOm95tV9A14n9xnkPkMgiOTGcOIzx161y9UbDZvfW4/pub WormBase Release Workflow]
  
 
= Release Management =
 
= Release Management =
 
When production is ready to updated for release WSXXX:
 
When production is ready to updated for release WSXXX:
  
Create a new [https://github.com/WormBase/website/pull/new/WormBase:production...master 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.
+
# Create a new [https://github.com/WormBase/website/pull/new/WormBase:master...staging pull request from staging to master].
 +
# Review all changes going into new release. Merge in the pull request.
 +
# Create a new [https://github.com/WormBase/website/pull/new/WormBase:production...master 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.
  
  

Latest revision as of 20:00, 11 August 2014

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. We use git and GitHub to help us manage development.

Overview Diagram

Git Workflow - WormBase4.png

Editable version of the diagram

Contributing

Whenever you begin work on a new issue you should create a new branch for it. Any new features should branch off staging. Once the feature is ready for testing, you can submit a pull request to staging for code review. Feature branches aren't necessarily branches in the main repository - they can in the main WormBase repository, or on a developer's fork. Read more on our branching strategy

git checkout -b myFeature staging

Now you can make your changes and commit some code. Read more on commit messages

git add /PATH/TO/UPDATED/FILE
git commit -m "Descriptive commit message"

When you're ready, you can push your branch to GitHub

git push origin myFeature

Continue making changes until your code is ready for a code review. Is my code ready for review?

When your code is ready, go to GitHub and create a Pull Request. More info on Pull Requests.

  1. Go to the repository where you pushed your changes
  2. Using the drop down, switch to your branch (e.g. myFeature)
  3. Click the green Compare & review button
  4. After reviewing all the changes, click on Create pull request in the header to send the pull request
  5. In the description, write a short summary of the issues (along with a link to the issue) 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 myFeature

Go to the original github issue:

  1. Add the Under testing label to your issue
  2. Comment on the issue to notify all involved that it is ready for testing. Add links for testing for the ease of testers.
  3. Another member of the WormBase group will close the issue once they have tested it

Note: You can view all merged pull requests using this link: https://github.com/WormBase/website/pulls?q=is%3Apr+is%3Amerged

Is my code ready for review?

Before you send a Pull Request, please make sure you have completed the following:

  • Written tests (API tests or REST tests) demonstrating the problem in the issue. More info on testing
  • Fix the problem (ie pass the tests)
  • Complete the issue as much as possible without curators seeing an example
  • Code style meeting the WormBase coding standards (indentation, comments, no debug statements)

What info should I include in a Pull Request?

To help your reviewer understand your code, please try to include the following in the Pull Request description

  • A link to the issue being addressed
  • Short summary of the problem
  • Some links to use for testing
  • Any other information that may be needed to testing (ie wormbase_local.conf changes, extra files needed, etc)

Commit messages

git commit -m "COMMIT MESSAGE GOES HERE"

Keep your commit message as descriptive as possible, reference any issues affected by the issue number (#YYY):

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

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

Code Review

All changes must go through a code review before being merged to the staging branch. At WormBase, this is done using Pull Requests. All members of the core development team are expected to keep an eye on the open Pull Requests and reviewing the ones they are assigned.

  • Test out the pull request (check out the branch)
  • Take a quick look at the code (are there comments? anything obvious missing)
  • Run the tests written for this issue
  • Leave a comment on the PR if you notice anything that needs to be fixed
  • Merge the PR if you think it looks good
    • Begin by merging staging into the feature branch.
    • If there are conflicts, ask the owner of the PR to help resolve them.

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.
  • 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, please close the issue.

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: all changes get pushed to the staging branch after code review. This code gets pushed immediately to staging.wormbase.org.
  • production: the code currently in production. Branched off of master at each release.

Feature branches

Any new features should branch off staging. Read more on feature branches in our contribution guidelines

Hotfixes

If a major bugfix is needed in production, create a hotfix branch from production. When finished, the branch needs to be merged (via PR/code review) 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

To close the fix, send a Pull Request to both the production and staging for code review. The reviewer will merge the branch.

Development Timeline

See: WormBase Release Workflow

Release Management

When production is ready to updated for release WSXXX:

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


git checkout production
git tag -a WSXXX

Links