Workflow
This article explains how development tasks are executed, starting with local code changes, resulting in production deployments.
All project work is performed via branches originating from the official project repository. The current production code for both the CalCentral and bCourses projects are available from the sis-berkeley-edu/calcentral repository.
New features, bug fixes, and other work, are only accepted into the CalCentral repository in the form of pull requests. Pull requests provide a method for developers to request that a project pull in (i.e. merge) contributions that another Github user has made to projects code. Once a pull request is created, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.
To keep the CalCentral repository clean, developers are asked to maintain their own remote branches under their own forks of the CalCentral repository.
The following only needs to be performed the first time you are setting up your workstation to work on the project.
Visit the sis-berkeley-edu/calcentral repository on Github, logged in as a Github user. Use the 'Fork' button to create your own fork of the repository.
Use 'git clone' to download the repository to your local projects directory.
cd ~/Projects
git clone https://github.com/your-username/calcentral.gitYou'll want to be able to easily create branches from the latest version of the
sis-berkeley-edu/calcentral repository, as it receives all official updates
made by other developers. In this workflow, updating the 'master' branch of your
fork is optional, as most work is done in branches created from the SIS
CalCentral repository.
Use the following command to add the SIS repository as a remote repository, serving as an alternative to the remote 'origin' for your fork.
cd calcentral
git remote add sis git@github.com:sis-berkeley-edu/calcentral.gitNow we're ready to move onto the work flow we will repeat each time we have a new task in JIRA that needs to be completed.
This section covers the workflow you will repeat each time you start a new development task.
This command fetches the updates from the official SIS CalCentral repository.
git fetch sisThese commands create a new branch using the master branch in the SIS
CalCentral repository (sis/master) as the source.
When beginning a new task that has been assigned to us in JIRA. We will want to create a new branch to contain all the modifications we've made to the code. The name of your branch is optional, however it may be useful to name your branch after the JIRA ticket you are working on. As the CalCentral project in JIRA uses the SISRP prefix for task ids, you could name your branches using the 'SISRP-12345' format used with JIRA tasks.
git checkout sis/master
git checkout -b SISRP-12345As you likely know well, modifications you make to the code in the local repository are committed to your new branch. This is an example of one commit. You'll hopefully be doing more than just one to your own branch.
$ git status
$ git add app/models/link.rb
$ git commit -m "Added validation for presence of user_roles"If you are creating a single commit, the commit message should cite the JIRA task it is related to. For example "SISRP-12345 - Added validation for presence of user_roles".
Some tasks that might not be related to a JIRA task include the following which do not affect the functionality of the system, and thus do not require QA / testing.
- HTML / code reformatting
- Modifications to Documentation / Comments
These non-JIRA tasks may be provided with a comment prefixed by 'NOJIRA', such as "NOJIRA - Updated comments for Link model"
Your modifications for the new branch need to be pushed remotely to your fork of the CalCentral project. When you try to push for the first time, Git should recommend the necessary command to setup the non-existent remote branch under your fork as the upstream remote.
$ git push
fatal: The current branch SISRP-12345 has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin SISRP-12345
$ git push --set-upstream origin SISRP-12345
Counting objects: 405, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (166/166), done.
Writing objects: 100% (336/336), 74.65 KiB | 0 bytes/s, done.
Total 336 (delta 192), reused 310 (delta 168)
To git@github.com:mygithubuser/calcentral.git
* [new branch] SISRP-12345 -> SISRP-12345
Branch SISRP-12345 set up to track remote branch SISRP-12345 from origin.After you've done this, you should be able to visit your repository, select to view the branches, and then select to view the branch you've just pushed remotely.
While viewing your remote branch, click on the 'Pull Request' link at the top to access the Pull request creation form.
Since your branch originated from the official CalCentral repository, it is the default base fork selected for the pull request.
The comments you provide on the pull request should include a link to the related JIRA task at the top, with the task ID (e.g. "SISRP-12345", "SISRP-12346") prefixing the title for the pull request. For the example above, the title might be "NOJIRA - Updated README", or "SISRP-12345 - Updated README".
After you've created the pull request, open the JIRA task and paste the URL for
the related pull request into a comment, thus completing cross linking between
the task and the work performed. It's recommended that you prefix the pull
request URL in the commend with PR:.
Example: (PR: https://github.com/sis-berkeley-edu/calcentral/pull/340)
It is policy to have another developer review your pull request. This provides them with the opportunity to:
- Learn more about the code in the system
- Detect mistakes or bugs (code duplication, inoperable code)
- Suggest best practices
- Review coding style
- Suggest alternative solutions
- Suggest changes to test coverage
After the developer has reviewed the code, they will merge the pull request.
The Bamboo continuous integration service will detect the merge, and automatically create and deploy a new build to the development server for CalCentral.
Once the Bamboo build is completed and deployed to the DEV and TST environments, mark your JIRA as 'Ready for TST'.
As you can see in the example above, the option to merge is surrounded by a yellow alert box that points out that the Travis CI build associated with the pull request has an error.
If you click on the 'Details' link, you will be taken to the page with details. On the left side of the page is a display of the other public projects being processed by Travis CI. In the right section you'll see the details of the build with a 'Build Matrix' section at the bottom listing various jobs.
If you click on the job ID, you will see the actual log from the job which points out the errors that were raised.
We see that the errors in the build are related to gem installation. We'll need to resolve this error so that Travis CI build testing jobs complete, and properly indicate an actual pass or failure of the build. For now we can complete the merge for the pull request knowing that the developer ran tests locally, and that we've reviewed the code ourselves.
It's important to ensure that your branch is up-to-date with the changes that
are in the master branch in the SIS repository. If you haven't configured your
repository with the SIS CalCentral repository setup as a remote repository
(noted above), you should do so now.
$ git remote add sis git@github.com:sis-berkeley-edu/calcentral.gitRebasing is like moving your branch forward to the state of the current CalCentral version, with all the changes you've made in your branch applied on top.
You can rebase one of your working branches, or your own master branch, using the following commands:
# checkout your branch
git checkout sisrp-12345-working-branch
# pull in changes from SIS remote repository
git fetch sis
# rebase your branch from the SIS 'master' branch
git rebase sis/master
# push the updates to your own master branch
git pushUsually this process will go smoothly, especially if you are rebasing your own 'master' branch from the SIS repository. If you rebase your own working branch, and your commits conflict with the changes in the SIS repository, you'll have to go through the steps to resolve the conflicts.
If conflicts are reported, use git status at any time to see which files need
modifications. After you've resolved the conflicts inside of the files, use
git add to re-stage the modified files, and then git rebase --continue to
continue the process. You can also use git rebase --abort if you have any
doubts and want to start over.
There are times when work that is assigned to you is requested so late that is does not make it into the 'master' branch before the QA branch is created from the 'master' branch. Make sure that you obtain authorization to do this from a project manager, and consult with the QA team to see if the task is within their scope. This practice is not recommended because it delays the QA and Operations team.
In such scenarios, do not create a QA pull request until your DEV pull request has been merged into 'master'. QA PRs that are open at the same time as DEV PRs will be closed.
At some point you may need to provide a pull request for the QA branch, issuing a fix for a bug that has come up during QA testing.
The first step in creating the fix is to create pull request for the 'master' branch, and then verify the fix on the CalCentral Development server cluster. Once this is completed, use 'git log' to view the information on the commit for your fix, and copy the SHA for that commit. In our example below, the SHA is 'b5847a2184991dfe6c963860aee3ef95a2bb4cd1'.
$ git log
commit b5847a2184991dfe6c963860aee3ef95a2bb4cd1
Author: Jason Miller <jason@redconfetti.com>
Date: Wed Apr 16 14:13:46 2017 -0700
SISRP-12345 - Converted CanvasUserProvisionController#user_import route from
GET to POST as per Rails 4 upgradeNext you will need to fetch all updates from remote CalCentral branches, checkout the remote QA branch, and then create a new branch from the remote 'qa' branch with the name of your fix. It's a good practice to add 'QA' into the name after the JIRA task ID, so that you can differentiate your QA branches from your master derived branches.
$ git fetch sis
$ git checkout sis/qa
$ git checkout -b SISRP-12345-QA-my-fixNext you'll want to use the git-cherry-pick command to pull the commit from your other development branch into this QA branch. You can use 'git log' to confirm that the commit is successfully showing up as the latest commit in your current branch. After this is done, push your branch to your Github fork. If you use 'git push', Git will prompt you with the command you can use to set your Github repository (a fork of the official sis-berkeley-edu/calcentral repository) as the default.
$ git cherry-pick b5847a2184991dfe6c963860aee3ef95a2bb4cd1
$ git log
$ git push
fatal: The current branch SISRP-12345-QA-my-fix has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin SISRP-12345-QA-my-fix
$ git push --set-upstream origin SISRP-12345-QA-my-fixOnce this is completed, go to view your Github project in your browser and you'll see your new branch mentioned with a 'Compare & pull request' button that you can use to create the pull request.
By default the pull request will be setup to request the merge of your commits into sis-berkeley-edu:master. You do not want this because your branch was based on the QA branch.
Click on the 'Edit' button on the far left and choose the 'qa' branch as the base for your pull request.
After this is done, you'll notice that the suggested title for your pull request is formatted better. Continue with the creation of the pull request as normal.
Some developers choose to maintain their own versions of the 'master' and 'qa' branches. It's important to use 'git branch -v -v' to monitor your local branches to ensure they are tracking the remote branch under your private repository (origin), instead of tracking the remote 'sis-berkeley-edu' branch. In this example we have 'sis' setup as the official SIS remote repository. After creating a new local 'qa' branch, it's tracking 'sis/qa'. We use 'git push -u origin qa' to ensure that it pushes to the 'origin' remote.
$ git branch -vv
* master 899f46c [origin/master] Merge pull request #5739 from dfkaye/SISRP-21962
$ git remote -v
sis git@github.com:sis-berkeley-edu/calcentral.git (fetch)
sis git@github.com:sis-berkeley-edu/calcentral.git (push)
origin git@github.com:redconfetti/calcentral.git (fetch)
origin git@github.com:redconfetti/calcentral.git (push)
$ git checkout -b qa sis/qa
Branch qa set up to track remote branch qa from sis.
Switched to a new branch 'qa'
$ git branch -vv
master 899f46c [origin/master] Merge pull request #5739 from dfkaye/SISRP-21962
* qa 8473fcd [sis/qa] Merge pull request #5785 from raydavis/qawip
$ git push -u origin qa
$ git push origin :qa
To git@github.com:redconfetti/calcentral.git
- [deleted] qa
$ git push -u origin qa
Counting objects: 22, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (22/22), done.
Writing objects: 100% (22/22), 2.90 KiB | 0 bytes/s, done.
Total 22 (delta 16), reused 0 (delta 0)
To git@github.com:redconfetti/calcentral.git
* [new branch] qa -> qa
Branch qa set up to track remote branch qa from origin.
$ git branch -vv
master 899f46c [origin/master] Merge pull request #5739 from dfkaye/SISRP-21962
* qa 8473fcd [origin/qa] Merge pull request #5785 from raydavis/qawip