Technical documentation for ArchivesSpace

View the Project on GitHub archivesspace/tech-docs

Building an ArchivesSpace release

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

Checkout the release branch and create release tag

If you are building a major or minor version (see, 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 merged to 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.)

    This generates docs/slate/source/ (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:

    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

As of v3.4.0, it should no longer necessary to build release notes manually.

To manually generate release notes:

./build/run doc:release_notes -Dcurrent_tag=v3.4.0 -Dtoken=$GITHUB_TOKEN

Edit Release Page As Neccessary

If there are any special considerations add them to the release page manually. 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](
before starting ArchivesSpace with the new version.

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. Consider the following, depending on current team consensus:


Delete merged and stale branches in Github as appropriate.


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.



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.