Table of Contents

Rolling an Evergreen Release

¡This is a work in progress. It will grow and change!

Helpful videos

These recordings show various release building activities.

Prerequisites

Make sure you are in an environment with your git ssh keys, since you will need to be pushing commits to the git server.

Make sure that you have OpenSRF installed in your environment.

To upload translations to Launchpad, you will also need to register an ssh key with Launchpad. See the 3.13 translation page for an example.

See Versioning for notes on the numbering scheme.

Install packager dependencies

# sudo make -f Open-ILS/src/extras/Makefile.install <os>-packager
$ sudo make -f Open-ILS/src/extras/Makefile.install ubuntu-jammy-packager

[Note that your Ubuntu version may be something other than 'jammy', or you may be using a different OS altogether. Substitute the appropriate version keyword – if you don't know your Ubuntu version off the top of your head, you can check the /etc/lsb-release file]

Confirm git credentials and username/email

The following steps will require you to commit your work and push to a remote git repository. If you are using a different environment than you usually use (for example, a fresh Docker container or new VM), make sure the following are correct.

If you are using a docker dev container, You can commit from inside the container, but push from the host machine – if you choose this approach, you should make sure the first two commands work from within the container, and the last two commands work from your host machine.

Setting How to check it How to fix it
Your user name Run the command: git config user.name and confirm that your name displays Run the command: git config –global user.name "My Name"
Your email address Run the command: git config user.email and confirm that your email displays Run the command: git config –global user.email me@example.com
The git remote you intend to push to (the Evergreen repo if you are a committer, the working/Evergreen repo if you are not) Run the command: git remote -v. Confirm that it includes git@git.evergreen-ils.org:Evergreen.git or git@git.evergreen-ils.org:working/Evergreen.git as a push url Run a command like: git remote add working git@git.evergreen-ils.org:working/Evergreen.git
Your SSH key to connect to the git remote Run the command git ls-remote. Confirm that it does not ask for git@git.evergreen-ils.org's password Securely copy or mount your private SSH key into the environment you will be using to push. For example, if you are creating a docker container for your work, you can add the flag -v ~/.ssh:/home/opensrf/.ssh to your docker run command to mount your .ssh directory. If you copy your private key to the VM or container, be sure to remove it or destroy the VM/container when you are done, since this key could allow somebody else to impersonate you.

Update relator codes (requires commit bit)

$ perl build/tools/relator_map > Open-ILS/src/templates/opac/parts/relators.tt2
$ cp Open-ILS/src/templates/opac/parts/relators.tt2 Open-ILS/src/templates-bootstrap/opac/parts/relators.tt2
# if 'git status' shows changes, commit them.
$ git commit -sm "Updating relator codes for XXX" Open-ILS/src/templates/opac/parts/relators.tt2 Open-ILS/src/templates-bootstrap/opac/parts/relators.tt2

Prepare release notes (for major version bumps only)

See also: Release Notes Process for DIG Release Coordinator

Cut a new release branch (such as rel_3_13): 

 git checkout -b rel_3_13 main

Create release notes:

First, the RELEASE_NOTE_NEXT piece. 

$ cd docs/RELEASE_NOTES_NEXT
$ ./create_release_notes.sh -r 3.13

After that script runs, you can remove 3.13-specific files from docs/RELEASE_NOTES_NEXT. Running the following in the docs/RELEASE_NOTES_NEXT directory should work: 

$ find . -mindepth 2 -name '*.txt' -exec git rm {} \;
$ find . -mindepth 2 -name '*.adoc' -exec git rm {} \;
$ echo "" > miscellaneous.adoc

Then, the extract release notes from the commit piece.

Next, use the `extract_release_notes_from_commits.pl` script to get the rest of the release notes. 

$ ../tools/extract_release_notes_from_commits.pl --help
$ ../tools/extract_release_notes_from_commits.pl --current-branch=rel_3_13_beta --prev-release-branch=main

For an alpha or beta release, this rough process is probably enough. For a real #.0 release, the resulting compiled release notes will need some TLC/cleanup.

Once you are at the .0 release, update line 3 of the antora.yml configuration file in your release branch so it reads 'version: 3.13' instead of 'version: latest'. 

$ vi docs/antora.yml

Then, update the version in the site.yml file on main branch to include rel_3_13 on line 9. 

$ vi docs/site.yml

Translations, Part 0: New Series Branch

This needs to be done once during the release cycle, typically at alpha or beta

Set up the new series branch using the instructions here: Setting Up a New Series Translation

Translations, Part 1: newpot (requires commit bit)

During each release starting with beta, get the latest template changes and apply them to the main branch you are working from in origin (main/rel_3_13/etc.). It is important to merge any new pot changes to origin so that Launchpad translations will get the latest strings that require translation.

Translations, Part 1a: Angular Staff Client Updates (requires a POEditor account)

Export strings for the Angular staff client and import them into POEditor, following the POEditor instructions. You will need to be a poeditor.com admin to do this.

Setting up your git branch

Create a local working branch for the release. This will contain changes applicable to only this release, and become the release "tag": 

$ git checkout -b tags/rel_3_13_1 rel_3_13

Translations, Part 2: update_pofiles

$ cd ../; 
# Clone the repository if necessary
$ bzr branch lp:~evergreen-bugs/evergreen/translation-export-main # for main branch
$ bzr branch lp:~evergreen-bugs/evergreen/translation-export-3.12 # for 3.12.x, e.g.
# If already cloned, simply pull in the latest changes
$ cd translation-export-SERIES; bzr pull; cd ../
# series here is "main" or "3.13" or whatever corresponding to the release
# that you are building
$ Evergreen/build/i18n/scripts/update_pofiles -l translation-export-SERIES -e Evergreen
$ cd Evergreen
$ git add -A build # pick up updates
$ git commit -sm "Translation updates - po files"

Translations, Part 2a: Update Angular Staff Client Translations (requires a POEditor account)

  1. Export (as xtb) any translations from the POEditor site that have over 50% translations available.
  2. Save them to Open-ILS/src/eg2/src/locale/ and commit using the following steps:
$ cp ~/download/path/messages.*.xtb ./Open-ILS/src/eg2/src/locale/
$ git add -A Open-ILS/src/eg2/src/locale/
$ git commit -asm "Translation updates - xtb files"

Update server upgrade documentation

Run the release builder script

Run the release builder script: 

$ export PATH=$PATH:/openils/bin
$ build/tools/make_release -v 3.13-beta -f origin/tags/rel_3_12_3

Additional notes on make_release options:

Note that you will get a lot of warnings related to the po translation files. These can be safely ignored.

Generate release docs

From the Evergreen directory: 

# copy README and release notes to ../release/
$ export RELEASE=3_12_0 # Increment for later release, 3_12_1 for example.
$ cp README ../release/README_$RELEASE
$ cp docs/RELEASE_NOTES_$RELEASE.adoc ../release/
$ cd ../release/
# in ../release/
$ asciidoc -a toc -a numbered README_$RELEASE
$ asciidoc -a toc -a numbered RELEASE_NOTES_$RELEASE.adoc
# delete the originals
$ rm README_$RELEASE RELEASE_NOTES_$RELEASE.adoc

Upload to web server (requires access to the evergreen-ils.org web server)

Move the release files into the correct download directories on the evergreen-ils.org web server (which is also known as lupin):

Because the release notes document is cumulative for each release series, a symbolic link exists for each release series so that (e.g.) RELEASE_NOTES_3_666.html points to the latest release in the series (e.g., RELEASE_NOTES_3_666.html → RELEASE_NOTES_3_666_7.html). Therefore, when uploading the release notes, update that symbolic link. When uploading the first alpha or beta for a series, it will be necessary to create the symbolic link.

When updating the downloads page to the website, the URL should use the symbolic link, not the release notes for the specific release, e.g., https://evergreen-ils.org/documentation/release/RELEASE_NOTES_3_666.html, not https://evergreen-ils.org/documentation/release/RELEASE_NOTES_3_666_7.html.

"Tag" Working Branch (requires commit bit)

git push origin tags/rel_3_13_0:tags/rel_3_13_0

"Forward-port" Version Upgrade Script (and, optionally, po files updates) (requires commit bit)

If doing a final release, you will need to copy the upgrade script you created to main and your current rel_x_y branch. If you skip copying to the rel_x_y branch in particular, your next point release will be missing an upgrade script in the middle of the chain!

For example, if you just created a release 3.12.6 and were on the branch tags/rel_3_12_6: 

git checkout rel_3_12
git checkout tags/rel_3_12_6 -- Open-ILS/src/sql/Pg/version-upgrade/3.12.5-3.12.6-upgrade-db.sql
git commit -sm "Forward-port 3.12.5-3.12.6 upgrade script"
git checkout main
git cherry-pick rel_3_12

Announcing and recording the release