Merge pull request #8100 from kenjis/docs-update-RELEASE.md

docs: update RELEASE.md

Author: kenjis

admin/RELEASE.md

@@ -2,7 +2,7 @@
 
 > Documentation guide based on the releases of `4.0.5` and `4.1.0` on January 31, 2021.
 >
-> Updated for `4.3.0` on January 10, 2023.
+> Updated for `4.4.3` on October 27, 2023.
 >
 > -MGatner, kenjis
 
@@ -53,12 +53,18 @@ Work off direct clones of the repos so the release branches persist for a time.
 * [ ] Clone both **codeigniter4/CodeIgniter4** and **codeigniter4/userguide** and
   resolve any necessary PRs
     ```console
+    rm -rf CodeIgniter4.bk userguide.bk
+    mv CodeIgniter4 CodeIgniter4.bk
+    mv userguide userguide.bk
     git clone [email protected]:codeigniter4/CodeIgniter4.git
     git clone [email protected]:codeigniter4/userguide.git
     ```
 * [ ] Vet the **admin/** folders for any removed hidden files (Action deploy scripts
   *do not remove these*)
-  * git diff --name-status origin/master admin/
+  ```console
+  cd CodeIgniter4
+  git diff --name-status origin/master admin/
+  ```
 * [ ] Merge any Security Advisory PRs in private forks
 
 ## Process
@@ -67,21 +73,24 @@ Work off direct clones of the repos so the release branches persist for a time.
 > been included with their PR, so this process assumes you will not be
 > generating much new content.
 
-* [ ] Create a new branch `release-4.x.x`
-* [ ] Update **system/CodeIgniter.php** with the new version number:
-  `const CI_VERSION = '4.x.x';`
-* [ ] Update **user_guide_src/source/conf.py** with the new `version = '4.x'` (if applicable)
-  and `release = '4.x.x'`
 * [ ] Replace **CHANGELOG.md** with the new version generated above
 * [ ] Update **user_guide_src/source/changelogs/{version}.rst**
-  * Set the date to format `Release Date: January 31, 2021`
   * Remove the section titles that have no items
 * [ ] Update **user_guide_src/source/installation/upgrade_{ver}.rst**
   * fill in the "All Changes" section, and add it to **upgrading.rst**
     * git diff --name-status origin/master -- . ':!system'
   * Remove the section titles that have no items
   * [Minor version only] Update the "from" version in the title. E.g., `from 4.3.x` → `from 4.3.8`
-* [ ] Commit the changes with `Prep for 4.x.x release` and push to origin
+* [ ] Run `php admin/prepare-release.php 4.x.x` and push to origin
+  * The above command does the following:
+    * Create a new branch `release-4.x.x`
+    * Update **system/CodeIgniter.php** with the new version number:
+      `const CI_VERSION = '4.x.x';`
+    * Update **user_guide_src/source/conf.py** with the new `version = '4.x'` (if applicable)
+      and `release = '4.x.x'`
+    * Update **user_guide_src/source/changelogs/{version}.rst**
+      * Set the date to format `Release Date: January 31, 2021`
+    * Commit the changes with `Prep for 4.x.x release`
 * [ ] Create a new PR from `release-4.x.x` to `develop`:
   * Title: `Prep for 4.x.x release`
   * Description:
@@ -119,6 +128,7 @@ Work off direct clones of the repos so the release branches persist for a time.
 * [ ] Run the following commands to install and test `appstarter` and verify the new
   version:
     ```console
+    rm -rf release-test
     composer create-project codeigniter4/appstarter release-test
     cd release-test
     composer test && composer info codeigniter4/framework
@@ -152,19 +162,21 @@ Work off direct clones of the repos so the release branches persist for a time.
     git switch -c 4.x
     git push origin HEAD
     ```
-* [ ] Publish any Security Advisories that were resolved from private forks
+* [ ] Request CVEs and Publish any Security Advisories that were resolved from private forks
   (note: publishing is restricted to administrators):
 * [ ] Announce the release on the forums and Slack channel
   (note: this forum is restricted to administrators):
   * Make a new topic in the "News & Discussion" forums:
     https://forum.codeigniter.com/forum-2.html
   * The content is somewhat organic, but should include any major features and
     changes as well as a link to the User Guide's changelog
+* [ ] Run `php admin/create-new-changelog.php <current_version> <new_version>`
+  * The above command does the following:
+    * Create **user_guide_src/source/changelogs/{next_version}.rst** and add it to
+      **index.rst** (See **next-changelog-*.rst**)
+    * Create **user_guide_src/source/installation/upgrade_{next_version}.rst** and add it to
+      **upgrading.rst** (See **next-upgrading-guide.rst**)
 * [ ] Create a PR for new changelog and upgrade for the next version
-  * Create **user_guide_src/source/changelogs/{next_version}.rst** and add it to
-    **index.rst** (See **next-changelog-*.rst**)
-  * Create **user_guide_src/source/installation/upgrade_{next_version}.rst** and add it to
-    **upgrading.rst** (See **next-upgrading-guide.rst**)
 
 ## Appendix
 

admin/create-new-changelog.php

@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+function replace_file_content(string $path, string $pattern, string $replace): void
+{
+    $file   = file_get_contents($path);
+    $output = preg_replace($pattern, $replace, $file);
+    file_put_contents($path, $output);
+}
+
+// Main.
+chdir(__DIR__ . '/..');
+
+if ($argc !== 3) {
+    echo "Usage: php {$argv[0]} <current_version> <new_version>" . PHP_EOL;
+    echo "E.g.,: php {$argv[0]} 4.4.3 4.4.4" . PHP_EOL;
+
+    exit(1);
+}
+
+// Gets version number from argument.
+$versionCurrent      = $argv[1]; // e.g., '4.4.3'
+$versionCurrentParts = explode('.', $versionCurrent);
+$minorCurrent        = $versionCurrentParts[0] . '.' . $versionCurrentParts[1];
+$version             = $argv[2]; // e.g., '4.4.4'
+$versionParts        = explode('.', $version);
+$minor               = $versionParts[0] . '.' . $versionParts[1];
+$isMinorUpdate       = ($minorCurrent !== $minor);
+
+// Creates a branch for release.
+system('git switch develop');
+system('git switch -c docs-changelog-' . $version);
+system('git switch docs-changelog-' . $version);
+
+// Copy changelog
+$changelog      = "./user_guide_src/source/changelogs/v{$version}.rst";
+$changelogIndex = './user_guide_src/source/changelogs/index.rst';
+if ($isMinorUpdate) {
+    copy('./admin/next-changelog-minor.rst', $changelog);
+} else {
+    copy('./admin/next-changelog-patch.rst', $changelog);
+}
+// Add changelog to index.rst.
+replace_file_content(
+    $changelogIndex,
+    '/\.\. toctree::\n    :titlesonly:\n/u',
+    ".. toctree::\n    :titlesonly:\n\n    v{$version}"
+);
+// Replace {version}
+$length    = mb_strlen("Version {$version}");
+$underline = str_repeat('#', $length);
+replace_file_content(
+    $changelog,
+    '/#################\nVersion {version}\n#################/u',
+    "{$underline}\nVersion {$version}\n{$underline}"
+);
+replace_file_content(
+    $changelog,
+    '/{version}/u',
+    "{$version}"
+);
+
+// Copy upgrading
+$versionWithoutDots = str_replace('.', '', $version);
+$upgrading          = "./user_guide_src/source/installation/upgrade_{$versionWithoutDots}.rst";
+$upgradingIndex     = './user_guide_src/source/installation/upgrading.rst';
+copy('./admin/next-upgrading-guide.rst', $upgrading);
+// Add upgrading to upgrading.rst.
+replace_file_content(
+    $upgradingIndex,
+    '/    backward_compatibility_notes\n/u',
+    "    backward_compatibility_notes\n\n    upgrade_{$versionWithoutDots}"
+);
+// Replace {version}
+$length    = mb_strlen("Upgrading from {$versionCurrent} to {$version}");
+$underline = str_repeat('#', $length);
+replace_file_content(
+    $upgrading,
+    '/##############################\nUpgrading from {version} to {version}\n##############################/u',
+    "{$underline}\nUpgrading from {$versionCurrent} to {$version}\n{$underline}"
+);
+
+// Commits
+system("git add {$changelog} {$changelogIndex}");
+system("git add {$upgrading} {$upgradingIndex}");
+system('git commit -m "docs: add changelog and upgrade for v' . $version . '"');

admin/next-changelog-minor.rst

@@ -1,3 +1,4 @@
+#################
 Version {version}
 #################
 
@@ -9,11 +10,13 @@ Release Date: Unreleased
     :local:
     :depth: 3
 
+**********
 Highlights
 **********
 
 - TBD
 
+********
 BREAKING
 ********
 
@@ -26,6 +29,7 @@ Interface Changes
 Method Signature Changes
 ========================
 
+************
 Enhancements
 ************
 
@@ -59,15 +63,19 @@ Helpers and Functions
 Others
 ======
 
+***************
 Message Changes
 ***************
 
+*******
 Changes
 *******
 
+************
 Deprecations
 ************
 
+**********
 Bugs Fixed
 **********
 

admin/next-changelog-patch.rst

@@ -1,3 +1,4 @@
+#################
 Version {version}
 #################
 
@@ -9,18 +10,23 @@ Release Date: Unreleased
     :local:
     :depth: 3
 
+********
 BREAKING
 ********
 
+***************
 Message Changes
 ***************
 
+*******
 Changes
 *******
 
+************
 Deprecations
 ************
 
+**********
 Bugs Fixed
 **********
 

admin/next-upgrading-guide.rst

@@ -12,15 +12,19 @@ Please refer to the upgrade instructions corresponding to your installation meth
     :local:
     :depth: 2
 
+**********************
 Mandatory File Changes
 **********************
 
+****************
 Breaking Changes
 ****************
 
+*********************
 Breaking Enhancements
 *********************
 
+*************
 Project Files
 *************
 

admin/prepare-release.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+function replace_file_content(string $path, string $pattern, string $replace): void
+{
+    $file   = file_get_contents($path);
+    $output = preg_replace($pattern, $replace, $file);
+    file_put_contents($path, $output);
+}
+
+// Main.
+chdir(__DIR__ . '/..');
+
+if ($argc !== 2) {
+    echo "Usage: php {$argv[0]} <version>" . PHP_EOL;
+    echo "E.g.,: php {$argv[0]} 4.4.3" . PHP_EOL;
+
+    exit(1);
+}
+
+// Gets version number from argument.
+$version      = $argv[1]; // e.g., '4.4.3'
+$versionParts = explode('.', $version);
+$minor        = $versionParts[0] . '.' . $versionParts[1];
+
+// Creates a branch for release.
+system('git switch develop');
+system('git switch -c release-' . $version);
+system('git switch docs-changelog-' . $version);
+
+// Updates version number in "CodeIgniter.php".
+replace_file_content(
+    './system/CodeIgniter.php',
+    '/public const CI_VERSION = \'.*?\';/u',
+    "public const CI_VERSION = '{$version}';"
+);
+
+// Updates version number in "conf.py".
+replace_file_content(
+    './user_guide_src/source/conf.py',
+    '/^version = \'.*?\'/mu',
+    "version = '{$minor}'"
+);
+replace_file_content(
+    './user_guide_src/source/conf.py',
+    '/^release = \'.*?\'/mu',
+    "release = '{$version}'"
+);
+
+// Updates release date in changelogs.
+$date = date('F j, Y');
+replace_file_content(
+    "./user_guide_src/source/changelogs/v{$version}.rst",
+    '/^Release Date: .*/mu',
+    "Release Date: {$date}"
+);
+
+// Commits
+system('git add -u');
+system('git commit -m "Prep for ' . $version . ' release"');