Building a release
- Pre-release steps
- Build the docs
- Build the release
- Post the release with release notes
- Post-release updates
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), start by creating a branch for the release and all future patch releases:
git checkout -b release-v1.0.xgit 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. We try to ensure that the “hotfix” is merged into both master and the release branch without the need to cherry-pick commits from one branch to the other. The reason is that cherry-picking creates a new commit (with a new commit id) that contains identical changes, which is not optimal for the repository history.
It is therefore preferable to start from the release branch when creating a “hotfix” that needs to be merged into both the release branch and master. The Pull Request should then be based on the release branch. After that Pull Request has been through Code review, QA and merged, a second Pull Request should be created to merge the updated release branch to master.
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 -b oh-no-some-migration-corrupts-some-data origin/release-v1.0.0( fixes problem )git commit -m "fix bad migration and add a migration to repair corrupted data"gh pr create -B release-v1.0.x --web( PR is reviewed and merged to the release branch)git checkout release-v1.0.xgit pullgit tag v1.0.1gh pr create -B master --web( PR is reviewed and merged to the master branch)
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.
-
Bootstrap your current development environment on the latest master branch by downloading all dependencies—JRuby, Gems, Solr, etc.
Terminal window build/run bootstrap -
Run the following checks (recommended):
Terminal window build/run rake -Dtask=check:localesbuild/run rake -Dtask=check:multiple_gem_versions -
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
-
API documentation depends on the archivesspace/slate submodule and on Docker. Slate cannot run on JRuby.
Terminal window git submodule initgit submodule update -
Run the
doc:api
task to generate Slate API and Yard documentation. (Note: the API generation requires a DB connection with standard enumeration values.)Terminal window ARCHIVESSPACE_VERSION=X.Y.Z APPCONFIG_DB_URL=$APPCONFIG_DB_URL build/run doc:apiThis generates
docs/slate/source/index.html.md
(Slate source document). -
(Optional) Run a docker container to preview API docs.
Terminal window docker-compose -f docker-compose-docs.yml upVisit
http://localhost:4568
to preview the api docs. -
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 todocs/build/api
.Terminal window 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
-
Build the YARD docs in the
docs/build/doc
directory:Terminal window ./build/run doc:yardoc
Commit built docs and push to Github pages
-
Double check that you are on a release branch (we don’t need this stuff in master) and commit the newly built documentation:
Terminal window git add docs/buildgit commit -m "release-vx.y.z api and yard documentation"Use
git subtree
to push the documentation to thegh-pages
branch:Terminal window git subtree push --prefix docs/build origin gh-pagesPublished 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:Terminal window git push origin :gh-pages
Building a release yourself
-
Building the actual release is very simple. Run the following:
Terminal window ./scripts/build_release vX.X.XReplace X.X.X with the version number. This will build and package a release in a zip file.
Building a release on Github
- There is no need to build the release yourself. Just push your tag to Github
and trigger the
release
workflow:Replace X.X.X with the version number. You can set the resulting release page to “draft” using the Github API.Terminal window git push vX.X.X
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:
export GITHUB_TOKEN={YOUR DEPLOYMENT TOKEN ON GITHUB}./build/run doc:release_notes -Dcurrent_tag=v3.4.0 -Doutfile=RELEASE_NOTES.md -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 workcorrectly. Please follow the [instructions for reindexing](https://archivesspace.github.io/tech-docs/administration/indexes.html)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:
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.