07. Deploying code changes

When to deploy changes to the server

When code that has been pushed to GitHub is ready to be tested, it is first deployed to the development server and tested by staff and by Selenium tests. If tests fail, code is rewritten, pushed to GitHub, and redeployed to the development server. Once code on the development server passes all internal and automated tests, it is deployed to the pre-production server, where it can be further tested by external users. All production changes must be accompanied by a TeamDynamix request. Development can continue on local machines and on the development server while tests proceed on the pre-production server.

NOTE that the files dspace/config/dspace.cfg and /foo.properties (in root) are managed by a separate process from the rest of the codebase. Any changes to those files should be committed to the Ansible project on GitLab or else an issue created there.

How to deploy changes

We are using the gitflow model, customized to reflect the fact that we have three servers (dev, pre-prod, and prod) instead of two, so "release branches" are created for each.

When code on vt_6_x_dev is ready to deploy to the development server, the pre-production server, or the production server, the product manager will merge all the commits to be deployed into the appropriate branch and notify the sysadmin that that branch should be deployed.

Development deployment branch is named vt_6_x_dev_deploy
Pre-production deployment branch is named vt_6_x_pprd_deploy
Production deployment branch is named vt_6_x_prod_deploy

Tagging commits

Before merging the development branch into a deployment branch, the last commit on the development branch should be tagged with [YYYY]_[MM]_[DD]_[sprintname] to reflect the deployment version. To tag a commit, first make sure you have checked out the development branch, then look at the latest commit:

git checkout [branchname]

git log

Then add the sprint tags to the most recent commit. For instance, if the most recent commit identifier begins with '432bm3...' and you are deploying all the changes made during the Aardvark sprint on August 20, 2015, you can add the sprint tag using lightweight tags with the command

git tag 2015_08_20_aardvark 432bm3

This tag will remain the same as it moves from deployment branch to deployment branch: it indicates the date the code was "finished" and the sprint during which the code changes were made.

Run git show [version tag] to check that the latest commit on the deployment branch is tagged with the version tag.

To push all tags up to the upstream GitHub remote repository, use

git push origin -u --tags

Merging changes

To merge commits from one branch into another, first check out the branch you want to move commits to, then merge (without "fast-forwarding") and specify the branch you want to move commits from:

To move commits from the catchall development branch to the development server:

git checkout vt_6_x_dev_deploy

git merge --no-ff vt_6_x_dev

To move commits from the development server to the pre-production server:

git checkout vt_6_x_pprd_deploy

git merge --no-ff vt_6_x_dev_deploy

To move commits from pre-production to production:

git checkout vt_6_x_prod_deploy

git merge --no-ff vt_6_x_pprd_deploy

Cherry-picking commits for the deployment branch

Merging will bring in all the commits from a particular branch to another branch. If you want to select only certain commits for the deployment branch, use the 'cherry-pick' command with the commit number. For example:

git checkout vt_6_x_dev_ (development branch)

git log (list the commits on that branch)

Write down or copy the commit number(s) you are interested in, e.g., ab12cd

git checkout vt_6_x_dev_deploy

git cherry-pick ab12cd

This will bring only the commit ab12cd from the development branch into the deployment branch.

Push the branch

Push the appropriate deployment branch to the GitHub repository.

git push

Notify ITS to deploy the changes to the appropriate server

Requests for any changes to the production system should go through 4Help, so there will be a record.

Mention if the requested deployment is the latest commit on the branch or an earlier commit.
Be sure to mention if there are any changes to files in the vtlibans project.
If there have been any changes to search filters or facets, ask for reindexing.
It is helpful to give them something to look for to check that the changes have occurred.
You will need to ask ITS to manually update the database on dev and/or, if desired. - Important: don't do this unless coordinated with Elements db update.
12/01/2016: If there is there is an "unprotected private key file" error in the /dspace/assetstore/ingest/etd-gradschool/log/cron-yyyy-mm-dd.log file, ask ITS to restrict the permissions, sudo -u vtechworks chmod 0700 /var/local/vtechworks/.ssh/id_rsa

Updating from DSpace core

Updates from the main DSpace repository to this project must be manually loaded. See Project Maintainer Instructions in Wiki.

Pull requests to the main DSpace project must be manually submitted. See Project Maintainer Instructions in Wiki.

Release notes

On the Tags list choose the associated tag for the release notes. When the production branch has been deployed, publish Release Notes on the GitHub repository with bullet points describing the changes that have been made. These can be drafted beforehand.