Differences

This shows you the differences between two versions of the page.

--- dev:release_process:evergreen:how_to_build [2024/05/13 15:39] – [Run the release builder script] aneiman
+++ dev:release_process:evergreen:how_to_build [2025/02/10 16:53] (current) – [Helpful videos] aneiman
@@ Line 10: / Line 10: @@
   * 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]]
+  * Feb 2025 [[https://youtu.be/PV1R8o8GFoI?si=ZLBRfKFWqOPgz4CV|3.15 Build Q&A]]
 ==== 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 [[https://code.launchpad.net/~evergreen-bugs/evergreen/translation-export-3.13|3.13 translation page for an example]].
 See [[::versioning|Versioning]] for notes on the numbering scheme.
@@ Line 23: / Line 28: @@
 <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
+$ sudo make -f Open-ILS/src/extras/Makefile.install ubuntu-jammy-packager
 </code>
-[Note that your Ubuntu version may be something other than 'focal'; substitute the appropriate version keyword]
+[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) ====
@@ Line 60: / Line 76: @@
 $ find . -mindepth 2 -name '*.txt' -exec git rm {} \;
 $ find . -mindepth 2 -name '*.adoc' -exec git rm {} \;
+$ echo "" > miscellaneous.adoc
 </code>
@@ Line 99: / Line 116: @@
 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.
-  * Update pot in Evergreen <code bash>$ cd build/i18n && make newpot</code>
+  * Update pot in the Evergreen directory as a non-root user <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>
@@ Line 126: / Line 143: @@
   * NOTE: See here to find the correct translation branch for the version you are building: https://code.launchpad.net/evergreen/+branches
+  * It will give you an error "You have not informed bzr of your Launchpad ID, and you must do this to write to Launchpad or access private data."  You can safely ignore this, since you will just need to read public data for the next step -- no writing or private data needed.
   * 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
+# 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
@@ Line 145: / Line 163: @@
 $ 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.13.0):
-<code perl>
-our $VERSION = '3.1300';
-</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.4" would be "3.1204".  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 3.13"
 </code>
@@ Line 184: / Line 187: @@
   * Use the highest numbered previous version for the second version value.
     * For example, building 3.13-beta, the script should start from the highest 3.12 release at the time of branching: <code bash>$ build/tools/make_release -v 3.13-beta -f origin/tags/rel_3_12_3</code>
-    * For a .0 release, the script should start from (probably) the release candidate: <code bash>$ build/tools/make_release -v 3.13.0 -f origin/tags/rel_3_13_rc</code>
+    * For a .0 release, the script should start from the highest point release in the previous series: <code bash>$ build/tools/make_release -v 3.13.0 -f origin/tags/rel_3_12_3</code>
     * For a point release, the script should start from the previous point release in the series: <code bash>$ build/tools/make_release -v 3.13.1 -f origin/tags/rel_3_13_0</code>
   * Use the -v flag when your branch name does not match the normal pattern, otherwise auto-detect works
@@ Line 208: / Line 211: @@
 <code bash>
 # copy README and release notes to ../release/
-$ export RELEASE=3_12
+$ 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/
@@ Line 225: / Line 228: @@
 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/''
+    * Final releases 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/''
+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) ====
@@ Line 239: / Line 245: @@
 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:
+<code bash>
+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
+</code>
 ==== 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]]