===== Rolling an Evergreen Release =====

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

==== Helpful videos ====

These recordings show various release building activities.

  * May 2023 [[https://www.youtube.com/watch?v=mdEhjFKMFTI|Cutting a Evergreen Release]]
  * Nov 2023 [[https://drive.google.com/file/d/1G0niyLAh55_mkgJVGn1GLFGHl_zEltcJ/view|Building 3.12, first session]]
  * Dec 2023 [[https://princeton.zoom.us/rec/play/zDAyi7Y852mQys4Y7txxJz8fpLooM9zbz3iosP9Ex-ulHmlQ0iSWXfe-5vB-9ke_WRT-HbMYAOsHvoEO.YiWoiCK3_85oGQxf?canPlayFromShare=true&from=share_recording_detail&continueMode=true&componentName=rec-play&originRequestUrl=https%3A%2F%2Fprinceton.zoom.us%2Frec%2Fshare%2Fwrmq5l5oEMGQyzXFJiXoww0NlAK3cH8sH4amQOrE9jO0hsSjZfcl2GGzTz9y9aL4.LybQWetrF2AEXvje|Building 3.12, second session]]

==== 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.

See [[::versioning|Versioning]] for notes on the numbering scheme.

==== Install packager dependencies ====

  * Install the **packager** dependencies using the Evergreen installer makefile:

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

[Note that your Ubuntu version may be something other than 'focal'; substitute the appropriate version keyword]

==== Update relator codes (requires commit bit) ====

  * During **beta** release building, update relator codes and commit the change to main (if necessary).  This happens before string freeze for translations, see https://bugs.launchpad.net/evergreen/+bug/1407507 for more details.

<code bash>
$ 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
</code>


==== Prepare release notes (for major version bumps only) ====

=> See also the [[evergreen-docs:release_notes_process|Release Notes Process for DIG Release Coordinator]]

  * Cut a new release branch (such as rel_3_7):
<code>
git checkout -b rel_3_7 main
</code>

  * Update the version in the antora configuration

<code bash>
$ vi docs/antora.yml
</code>

edit 'latest' -> '3.7'

  * Create release notes

<code bash>
$ cd docs/RELEASE_NOTES_NEXT
$ ./create_release_notes.sh -r 2_8
</code>

  * Remove 2.8-specific files from docs/RELEASE_NOTES_NEXT.
    * Running the following in the docs/RELEASE_NOTES_NEXT directory should work:
<code bash>
$ find . -mindepth 2 -name '*.txt' -exec git rm {} \;
$ find . -mindepth 2 -name '*.adoc' -exec git rm {} \;
</code>

  * <fixme> Make use of the extract_release_notes_from_commits.pl script.
    * The script parses commits to pull the following:
      * Release notes for bugs that use the Release-note: tag.
      * Contributors
      * Sponsors
    * See [[https://bugs.launchpad.net/evergreen/+bug/2051874|Bug #2051874]] for details.
    * Update these instructions.

<code bash>
$ ../tools/extract_release_notes_from_commits.pl --help
$ ../tools/extract_release_notes_from_commits.pl --current-branch=rel_3_7_1 --prev-release-branch=rel_3_7_0
</code>

  * Integrate the results into the release notes. 

  * Stage your changes and commit the release notes: `git commit -sm "3.7 release notes"`

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.


==== 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_1/etc.).  It is important to merge any new pot changes to origin so that Launchpad translations will get the latest strings that require translation.
    * Update pot in Evergreen <code bash>$ cd build/i18n && make newpot</code>
    * From the Evergreen directory, run the python script to commit any changes that do more than modify metadata <code bash>python3 build/i18n/scripts/add_translations.py -c # use -h option for help</code>

==== Translations, Part 1a: Angular Staff Client Updates (requires a POEditor account) ====
    * Export strings for the Angular staff client and import them into POEditor, following these [[: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": 


<code bash>$ git checkout -b tags/rel_3_13_1 rel_3_13</code>

==== Translations, Part 2: update_pofiles ====

  * Next, clone (or update) the translations repository in a new directory as a peer to Evergreen. This pulls in translations from Launchpad:

<code bash>
$ 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 ../
</code>

  * NOTE: See here to find the correct translation branch for the version you are building: https://code.launchpad.net/evergreen/+branches

  * Then, sync translated files with Evergreen. Update PO files in the appropriate branch in origin:

<code bash>
# series here is "main" or "3.10" 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"
</code>

==== Translations, Part 2a: Update Angular Staff Client Translations (requires a POEditor account) ====
  - [[https://wiki.evergreen-ils.org/doku.php?id=poeditor|Export (as xtb) any translations]] from the POEditor site that have over 50% translations available.
  - Save them to ''Open-ILS/src/eg2/src/locale/'' and commit using the following steps:
<code bash>
$ 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"
</code>

==== Other version number changes ====

  * Edit ./Open-ILS/src/perlmods/lib/OpenILS.pm and set (e.g., for 3.1.1):
<code perl>
our $VERSION = '3.0101';
</code>

  * NOTE: The version string is two digits for each level after the decimal, so for example "3.0.5" would become "3.0005".  "3.12.0" would be "3.1200".  If it is a beta or release candidate, do not include "beta" or "rc", just use the numeric version. 

  * Commit the version change

<code bash>
$ git commit -asm "bumping Perl version string for 2.8"
</code>

==== Update server upgrade documentation ====

  * Replace release version placeholders (X.X.X) with the actual version numbers in docs/modules/installation/pages/server_upgrade.adoc
  * * In vim, '':%s/3.X.X/3.12.3/'' will do the trick
  * If you are creating a beta or rc, add a hyphen and then beta or rc.  For example, 3.12-rc.
  * Replace the previous version placeholder (e.g. 3.X.W) with the last release number.
  * * In vim, '':%s/3.X.W/3.12.2/'' will do the trick
  * Double check the correct minimum version of OpenSRF.
  * If the minimum version of OpenSRF has changed, also update the OpenSRF version number in docs/modules/installation/pages/server_installation.adoc

==== Run the release builder script ====

  * Run the release builder script
<code bash>
$ export PATH=$PATH:/openils/bin
$ build/tools/make_release -v 2.8.0 -f origin/tags/rel_2_7_3
</code>

  * Additional notes on make_release options:
    * Use the -v flag when your branch name does not match the normal pattern, otherwise auto-detect works
    * Use the -j flag to point at wherever your OpenSRF javascript lib source is, if not already installed
      * -j ~/Git/OpenSRF/src/javascript/
    * The -f flag sets the branch "from" which this release this being made from, aka what was the last version of Evergreen prior to the one you're making. This guides the make_release towards creating a version-upgrade from X to Y. 
    * You can add the -r option to edit the upgrade script before it goes into the tarball. This may be necessary if tables that get altered in the upgrade scripts also have updates or inserts of new data.
    * Enhanced Concerto Dataset upgrade *experimental
      * This is optional, but if enough of the database tables have changed, it's a good idea.
      * -H <postgres server hostname>
      * -U <postgres username> # needs SUPERUSER and CREATEDB
      * -P <database password>
      * -O <database port>
      * Omitting -H will cause make_release to skip the enhanced concerto upgrade steps.

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:

<code bash>
# copy README and release notes to ../release/
$ export RELEASE=3_12
$ 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
</code>



==== 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):
    * Previews / alphas / betas / release candidates go in ''/var/www/open-ils.org/downloads/previews/'' 
    * Final releases and ChangeLog-* go in ''/var/www/open-ils.org/downloads/''
    * Install docs / README_* go in ''/var/www/open-ils.org/documentation/install/''
    * Release notes go in ''/var/www/open-ils.org/documentation/release/''

==== "Tag" Working Branch (requires commit bit) ====

<code bash>
git push origin tags/rel_3_12_1:tags/rel_3_12_1
</code>

==== "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!

==== Announcing and recording the release ====
    * Update evergreen_history.txt file in history repo with release dates.
    * Release team / outreach committee make announcements following [[https://docs.google.com/document/d/1FpCvnAgL0TiHL3L-lNWbEd7FLBzVs6UV0L1kIoN70Jw/edit?usp=sharing|publicity checklist]]