Building an ArchivesSpace release

• Pre-Release Steps
• Build the Docs
• Build the Release
• Post the Release with Release Notes
• Post-Release Steps

Clone the git repository

When building a release it is important to start from a clean repository. The safest way of ensuring this is to clone the repo:

git clone https://github.com/archivesspace/archivesspace.git

Checkout the release branch and create release tag

If you are building a major or minor version (see [https://semver.org])(semver.org)), start by creating a branch for the release and all future patch releases:

git checkout -b release-v1.0.x
git tag v1.0.0

If you are building a patch version, just check out the existing branch and see below:

git checkout release-v1.0.x

Patch versions typically arise because a regression or critical bug has arisen since the last major or minor release. If the “hotfix” has been merged to the release branch, it will need to be cherry-picked back to the master branch. If it has been merged to the master branch (more likely given current code review / QA workflow), it (they) will need to be cherry-picked to the release branch.

Consider the following scenario. The current production release is v1.0.0 and a critical bug has been discovered. In the time since v1.0.0 was released, new features have been added to the master branch, intended for release in v1.1.0:

git checkout master
git checkout -b oh-no-some-migration-corrupts-some-data
( fixes problem )
git commit -m "fix bad migration and add a migration to repair corrupted data"
gh pr create --web
( PR is reviewed and approved on Github, QA'd, then merged to master)
git pull master
git checkout release-v1.0.x
git cherry-pick [SHA of hotfix commit]
git push origin release-v1.0.x
git tag v1.0.1

Pre-Release Steps

Run the ArchivesSpace rake tasks to check for issues

Before proceeding further, it’s a good idea to check that there aren’t missing translations or multiple gem versions.

1. Bootstrap your current development environment on the latest master branch by downloading all dependencies–JRuby, Gems, Solr, etc.

   build/run bootstrap
   

2. Run the following checks (recommended):

   build/run rake -Dtask=check:locales
   build/run rake -Dtask=check:multiple_gem_versions
   

3. Missing locales do not need to be addressed for a Release Candidate, but should be noted and provided prior to a full release. If multiple gem versions are reported, that should be addressed prior to moving on.

Build and Publish the API and Yard Docs

API docs are built using the submodule in docs/slate and Docker. YARD docs are built using the YARD gem. At this time, they cover a small percentage of the code and are not especially useful.

Build the API docs

1. API documentation depends on the archivesspace/slate submodule and on Docker. Slate cannot run on JRuby.

   git submodule init
   git submodule update
   

2. Run the doc:api task to generate Slate API and Yard documentation. (Note: the API generation requires a DB connection with standard enumeration values.)

   ARCHIVESSPACE_VERSION=X.Y.Z APPCONFIG_DB_URL=$APPCONFIG_DB_URL build/run doc:api
   

   This generates docs/slate/source/index.html.md (Slate source document).

3. (Optional) Run a docker container to preview API docs.

   docker-compose -f docker-compose-docs.yml up
   

   Visit http://localhost:4568 to preview the api docs.

4. Build the static api files. The api markdown document should already be in docs/slate/source (step 2 above). The api markdown will be rendered to html and moved to docs/build/api.

   docker run --rm --name slate -v $(pwd)/docs/build/api:/srv/slate/build -v $(pwd)/docs/slate/source:/srv/slate/source slatedocs/slate build
   

Build the YARD docs

1. Build the YARD docs in the docs/build/doc directory: shell ./build/run doc:yardoc

Commit built docs and push to Github pages

1. Double check that you are on a release branch (we don’t need this stuff in master) and commit the newly built documentation:

   git add docs/build
   git commit -m "release-vx.y.z api and yard documentation"
   

   Use git subtree to push the documentation to the gh-pages branch:

   git subtree push --prefix docs/build origin gh-pages
   

   Published documents should appear a short while later at: http://archivesspace.github.io/archivesspace/api http://archivesspace.github.io/archivesspace/doc

   Note: if the push command fails you may need to delete gh-pages in the remote repo:

   git push origin :gh-pages
   

Building a release yourself

1. Building the actual release is very simple. Run the following:

   ./scripts/build_release vX.X.X
   

   Replace X.X.X with the version number. This will build and package a release in a zip file.

Building a release on Github

1. There is no need to build the release yourself. Just push your tag to Github and trigger the release workflow:

   git push vX.X.X
   

   Replace X.X.X with the version number. You can set the resulting release page to “draft” using the Github API.

Create the Release with Notes

Build the release notes

After reviewing the above, build the release notes:

export GITHUB_API_TOKEN={YOUR DEPLOYMENT TOKEN ON GITHUB}
build/run thor -Dtask="doc:release_notes" -Dtask_args="--token=$GITHUB_API_TOKEN --current_tag=v3.3.0 --previous_tag=v3.2.0 --out=RELEASE_NOTES.md"

Review the Notes

Many of the automatically generated sections (especially the config changes) will require some manual review/copy-editing.

Other considerations

If there are any special considerations add them here. Special considerations might include changes that will require 3rd party plugins to be updated or a that a full reindex is required.

Example content:

This release requires a **full reindex** of ArchivesSpace for all functionality to work
correctly. Please follow the [instructions for reindexing](https://archivesspace.github.io/tech-docs/administration/indexes.html)
before starting ArchivesSpace with the new version.

Save the draft

When the placeholder sections have been updated or removed save the draft and share with the team.

Post release updates

After a release has been put out it’s time for some maintenance before the next cycle of development clicks into full gear:

Branches

Delete merged and stale branches in Github as appropriate.

Milestones

Close the just-released Milestone, adding a due date of today’s date. Create a new Milestone for the anticipated next release (this can be changed later if the version numbering is changed for some reason).

Test Servers

Review existing test servers, and request the removal of any that are no longer needed (e.g. feature branches that have been merged for the release).

GitHub Issues

Review existing opening GH issues and close any that have been resolved by the new release (linking to a specific PR if possible). For the remaining open issues, review if they are still a problem, apply labels, link to known JIRA issues, and add comments as necessary/relevant.

Accessibility Scan

Run accessibility scans for both the public and staff sites and file a ticket for any new and ongoing accessibility errors.

PR Assignments

Begin assigning queued PRs to members of the Core Committers group, making sure to include the appropriate milestone for the anticipated next release.

Dependencies

Gems

Take a look at all the Gemfile.lock files ( in backend, frontend, public, etc ) and review the gem versions. Pay close attention to the Rails & Friends ( ActiveSupport, ActionPack, etc ), Rack, and Sinatra versions and make sure there have not been any security patch versions. There usually are, especially since Rails sends fix updates rather frequently.

To update the gems, update the version in Gemfile, delete the Gemfile.lock, and run ./build/run bootstrap to download everything. Then make sure your test suite passes.

Once everything passes, commit your Gemfiles and Gemfile.lock files.