From aedb486d66305344671fd60c38305fe918443c85 Mon Sep 17 00:00:00 2001
From: totten <totten@civicrm.org>
Date: Mon, 23 Nov 2020 22:54:42 +0000
Subject: [PATCH] Update 5.x-patch.md

---
 doc/5.x-patch.md | 52 ++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 41 insertions(+), 11 deletions(-)

diff --git a/doc/5.x-patch.md b/doc/5.x-patch.md
index e4c2bed..5a43678 100644
--- a/doc/5.x-patch.md
+++ b/doc/5.x-patch.md
@@ -4,28 +4,58 @@
 
 See [Prerequisites](any-prereq.md)
 
-## 1: (If you haven't already) Set the final version to `5.X.Y`
+## 1A: Repo updates (PR flow; typical)
+
+Prepare patches for the `5.X` branch via PR.
+
+In tandem with the PRs, prepare the [draft release notes](https://docs.google.com/spreadsheets/d/1uJAiVf0IsBfY5PUarKTeztC8z6qMmtFnfLk8Gd4cJbQ/edit?usp=sharing).
+
+After all the substantive PRs have been merged, prepare a new PR to bump-up the version number and copy-in the release-notes:
 
 ```bash
 cd ~/src/master
-git checkout 5.X
-git pull --ff-only origin 5.X
+git checkout origin/5.X -b 5.X-bumpY
+
+# Set the final version to `5.X.Y`
+cat xml/version.xml
 ./tools/bin/scripts/set-version.php 5.X.Y --commit
-git push origin 5.X
+
+# Add the release notes
+vi release-notes.md release-notes/5.X.Y.md
+git add release-notes.md release-notes/5.X.Y.md
+git commit
 ```
 
-## 2: (If you haven't already) Backport patches to `5.X` branch
+Submit `5.X-bumpY` as a new PR.
+
+Use the Github GUI for final copy-editing of the notes.
 
-e.g.
+## 1B: Repo updates (Abridged flow)
+
+Plan the patchset and [generate release notes](https://docs.google.com/spreadsheets/d/1uJAiVf0IsBfY5PUarKTeztC8z6qMmtFnfLk8Gd4cJbQ/edit?usp=sharing). Then update the corresponding `5.X` branch:
 
 ```bash
 cd ~/src/master
 git checkout 5.X
+
+# Cherry-pick any patches
 git cherry-pick abcd1234abcd1234 
 git push origin 5.X
+
+# Set the final version to `5.X.Y`
+cat xml/version.xml
+./tools/bin/scripts/set-version.php 5.X.Y --commit
+
+# Add the release notes
+vi release-notes.md release-notes/5.X.Y.md
+git add release-notes.md release-notes/5.X.Y.md
+git commit
+
+# Push
+git push origin 5.X
 ```
 
-## 3: Sanity checks
+## 2: Sanity checks
 
 * Check open PRs for `5.X`: https://github.com/civicrm/civicrm-core/pulls
 * Check release notes: https://github.com/civicrm/civicrm-core/blob/5.X/release-notes.md
@@ -37,7 +67,7 @@ git push origin 5.X
     * Current git repos: `civi-git-table --fetch 5.X.Y 5.X`
     * Draft tarball: https://download.civicrm.org/latest/branch/5.X/LATEST/civicrm-X.Y.Z-drupal-LATEST.tar.gz/inspect
 
-## 4: Prepare and identify the final tarballs
+## 3: Prepare and identify the final tarballs
 
 In Jenkins, ensure that the final tarballs have been prepared. Run the job manually if you're impatient.
 
@@ -51,7 +81,7 @@ gsutil ls gs://civicrm-build/5.2/*json
 
 For example, we might pick `gs://civicrm-build/5.2/civicrm-5.2.1-201705030600.json`.
 
-## 5: Publish
+## 4: Publish
 
 You can do the full process in one command:
 
@@ -90,7 +120,7 @@ To ensure the various tags were published and match the branches, use `civi-git-
 civi-git-table --fetch 5.16.0 5.16.1 5.16
 ```
 
-## 6: Update `versions.json`
+## 5: Update `versions.json`
 
 Services such as the `civicrm.org` download page and the in-app version
 check depend on a file named `versions.json`. Update this.
@@ -125,7 +155,7 @@ And
 popd
 ```
 
-## 7: Make new versions visible on download sites
+## 6: Make new versions visible on download sites
 
 Log into https://civicrm.org/user and clear the page-cache in https://civicrm.org/admin/config/development/performance
 
-- 
GitLab