In October 2016, the CASA team will begin using the new Atlassian software suite. The suite includes a newer version of JIRA, the BitBucket revision control system (which uses git under the hood), the Bamboo continuous integration server, and the Confluence internal documentation server (similar to a wiki) and calendar system. Developer instructions on the details of using each of these systems will be provided before the transition, but we first need to decide on the overall development, build, and test workflow. To leverage the power of this suite of software some changes need to be made to our current workflows. This document describes the current proposed workflow.

The continuous integration process includes building, verifying, and validating the CASA code base. 

Work request details will be captured in JIRA tickets. The JIRA ticket workflow is described in the DMSD Software Development Processes document. The build and test workflow is designed to work in conjunction with the JIRA ticket workflow.

git Nomenclature

If you are unfamiliar with the distributed revision control paradigm used by git, this section will explain some important terms used below. Please also review Revision Control Processes.

Within git the top-level branch is the 'master'. To begin work on a new issue you will first create a branch from master. All code changes related to your issue will be made on this branch and when the work is complete and fully tested the branch will be merged back to master.

In distributed revision control, each code contributor has a 'clone' (or copy) of the full repository. The source repository from which your clone was derived is called the 'origin'. In the normal workflow described below, origin exists on the BitBucket server and is monitored by the Bamboo continuous integration system. If you create a branch using the BitBucket/JIRA web interface and then clone the BitBucket repository to your local machine, you will have a local copy of the master branch and can then check out the new branch to begin development.

Your code changes should be made and committed on your branch in your local cloned repository. When you are ready to share your committed changes with others, you can push your changes to origin.  This will trigger automated and manual processes, described below.  When your work has been fully tested and you are ready to merge changes back to master, you initiate a 'pull request'.  The person responsible for merging changes to master will review your request and pull your changes into the master branch.

Code changes while in the JIRA "Scheduled" state

Actual development work will be done while a JIRA ticket is in the "Scheduled" state. See Figure 1 for a graphic description of the workflow described here.

When the ticket enters the scheduled state, you will create a branch off of the master branch and check out the branch on your local machine. In the JIRA ticket, click on the "Create branch" link in the right column.  This will take you to a Bitbucket login page.  If you do not have access, email the NRAO helpdesk (web help) to be added to the bitbucket users group. After logging in, a dialog box will guide you through the steps to create a feature/ or bugfix/ branch branched from master.  An Engineering Task should be a feature branch.

In the course of development, you should occasionally push your code changes back to the BitBucket server (origin) after merging your updated master branch into it.   This push will trigger Bamboo to use the CI plan to build your branch and run automated test suite 0 ("package" and "smoke" tests) and test suite 1 ("verification" and "validation" tests) for branches with bugfix/ and feature/ prefixes.  The build and test sequence will take 30 minutes to an hour if successful. This plan does not do any packaging.

The outcome of this build and test will be emailed to you by Bamboo if you add the CI branch to your "Favourite" branches:

1. After you push your code changes to origin, go to the "Issue Links" section of the JIRA ticket. In the Bamboo Branches list, you should see CASA > CI > [your_branch]. Click this link to log into Bamboo and see the CI build page for this branch.
2. In the upper right of the page, you will see an "Actions" pull-down menu. Click the option to make it a "Favourite branch".  Now you will get notifications for failed builds and the first successful build after a failed build. The "Actions" menu also contains an option to "Unfavourite branch".
3. Note the issue type symbol, ticket name, descriptions, and status are listed in the header. Click on the ticket name to return to JIRA.
4. If you don't wish to receive email notifications, just use the CI link in the JIRA ticket to check on the build status.

If the build or test sequence fails, the problem could be in your code changes, or it could be in code changes merged from the master branch. Notify the build team if you believe the problem exists in code changes on master. However, please keep in mind that changes previously merged to master have already been through the automated and manual test process described below. 

Switching to the JIRA "Ready to Verify" state

When finished with an assignment you should push the last of your code changes to origin and change the JIRA ticket status to “Ready to Verify.” See Figure 2 for a graphic description of the workflow described here.

Changing the ticket status to “Ready to Verify” will signal Bamboo to use the "Branch Package" plan to perform a build and run test suites 0, 1, and 2 for bugfix and feature branches. The build and test sequence will take several hours if successful, or less time if unsuccessful. The outcome of this build and test will be emailed to you by Bamboo if you make it a "Favorite branch" as above using the Branch Package link listed in the ticket's Issue Links. If the build and tests are successful, this plan creates downloadable packages (.dmg and .tar.gz).

Next, a branch is created in the "Branch Critical Test" plan and added to the Issue Links. This plan runs Test Suite 2 on the packaged application and, if successful, adds links to the packages in JIRA ticket Comments added by the "CASA adm account".  You should receive email notification for these comments, just like any other comment.

After passing the automated tests, the project manager (PM) or group lead (GL) will assess the verification status. This assessment will primarily consist of making sure the automated processes worked properly. Additional manual testing by the test team may be requested. If any problems are found the ticket will return to the “Scheduled” state and be reassigned to you.

Switching to the JIRA "Ready to Validate" state

When satisfied with the test results, the PM or GL will change the ticket status to “Ready to Validate.” If some time has passed since the package links were added while the ticket was under verification, you may need to update master, merge it into your development branch, and push to origin again to produce a new, updated package.  The ticket will then undergo the usual validation testing process by the User Test team using the package links. A failure in this stage will cause the ticket to return to the "Scheduled" state and be reassigned to you, restarting the workflow.  It is important to update the submodules in your branch manually in your local repository before pushing any changes to origin.  Since the Branch Package branch for this ticket has already been created, any subsequent pushes to origin will automatically cause a successful CI build to launch the Branch Package plan even if the ticket remains "Scheduled" and is not advanced to "Ready to Verify".

If the ticket passes validation, the status is changed to “Resolved” and reassigned to the developer. Here you should update applicable user documentation. When finished, make a pull request from JIRA/Bitbucket to inform the build team that your branch is ready to be merged to the master branch. Include release notes in the pull request description.  At this point, you may change the ticket status to "Complete."

In the final part of the test process, Bamboo runs the "Master Package" plan nightly to create packages containing new commits to the master branch, then uses the "Master Critical Test" plan to run Test Suite 3 (long running validation and regression tests). These tests may take up to 24 hours to complete and are not directly connected to the branch lifecycle.