chore: port the release tooling to Markdown

.github/scripts/validate-version

@@ -6,14 +6,9 @@ if [[ -z $1 ]]; then
     exit 1
 fi
 
-FILES=("system/CodeIgniter.php" "user_guide_src/source/conf.py")
-LENGTH="${#FILES[@]}"
+CHANGELOG="docs/changelogs/v$1.md"
 
-for FILE in "${FILES[@]}"; do
-    COUNT="$((COUNT + $(grep -c "$FILE" -e "'$1'")))"
-done
-
-if [[ $COUNT -ne $LENGTH ]]; then
+if ! grep -q -e "'$1'" system/CodeIgniter.php || [[ ! -f $CHANGELOG ]] || grep -q -e "^Release Date: Unreleased" "$CHANGELOG"; then
     echo "CodeIgniter version is not updated to v"$1""
     exit 1
 fi

admin/RELEASE.md

@@ -216,7 +216,7 @@ Lines that start with `D` are removed files. Make sure none of them is needed by
 
 Skip this step if the release has no security fixes.
 
-Merge any security advisory pull requests from the private forks. Each fix must also be documented in the `SECURITY` section of **user_guide_src/source/changelogs/v$VERSION.rst**, because step 7 copies that section into **CHANGELOG.md**.
+Merge any security advisory pull requests from the private forks. Each fix must also be documented in the `SECURITY` section of **docs/changelogs/v$VERSION.md**, because step 7 copies that section into **CHANGELOG.md**.
 
 ### 7. Generate `CHANGELOG.md`
 
@@ -244,12 +244,12 @@ Copy the result into **CHANGELOG.md** and match the format of the existing entri
 
 ### 8. Update the detailed changelog
 
-Edit **user_guide_src/source/changelogs/v$VERSION.rst**.
+Edit **docs/changelogs/v$VERSION.md**.
 Remove every section title that has no items under it.
 
 ### 9. Update the upgrade guide
 
-Edit the upgrade guide page for the version in **user_guide_src/source/installation/**. The file name is `upgrade_` followed by the version without dots, so `4.7.6` is **upgrade_476.rst**.
+Edit the upgrade guide page for the version in **docs/installation/**. The file name is `upgrade_` followed by the version without dots, so `4.7.6` is **upgrade_476.md**.
 
 Preview the generated content:
 
@@ -284,8 +284,8 @@ The script does the following:
 
 - Creates the branch `release-$VERSION` from `develop`, replacing any local branch of the same name.
 - Sets `CI_VERSION` in **system/CodeIgniter.php** to `$VERSION`.
-- Sets `version` (for example `4.7`) and `release` (for example `4.7.6`) in **user_guide_src/source/conf.py**.
-- Sets the release date in **user_guide_src/source/changelogs/v$VERSION.rst** (format `Release Date: January 31, 2021`).
+- Sets the minor version (for example `4.7`) in the title `## Version 4.7` of **docs/changelogs/index.md**.
+- Sets the release date in **docs/changelogs/v$VERSION.md** (format `Release Date: January 31, 2021`).
 - Updates the title and version in **phpdoc.dist.xml**.
 - Updates **admin/starter/builds**: `LATEST_RELEASE` becomes `^<minor>` and `NEXT_MINOR` becomes `^<next minor>-dev`.
 - Commits everything, including your uncommitted edits to tracked files, as `Prep for $VERSION release`.
@@ -490,8 +490,9 @@ php admin/create-new-changelog.php $VERSION $NEXT_VERSION
 
 The script does the following:
 
-- Creates **user_guide_src/source/changelogs/v$NEXT_VERSION.rst** from **admin/next-changelog-patch.rst** and adds it to **index.rst**.
-- Creates the upgrade guide stub from **admin/next-upgrading-guide.rst** and adds it to **upgrading.rst**.
+- Creates **docs/changelogs/v$NEXT_VERSION.md** from **admin/next-changelog-patch.md** and adds it to **index.md**.
+- Creates the upgrade guide stub from **admin/next-upgrading-guide.md** and adds it to **upgrading.md**.
+- Adds both pages to **docs/.nav.yml**.
 - Sets `CI_VERSION` to `$NEXT_VERSION-dev`.
 - Creates the branch `docs-changelog-$NEXT_VERSION` from `develop` and commits.
 

admin/create-new-changelog.php

@@ -38,13 +38,13 @@ function replace_file_content(string $path, string $pattern, string $replace): v
 }
 
 // Copy changelog
-$newChangelog   = "./user_guide_src/source/changelogs/v{$newVersion}.rst";
-$changelogIndex = './user_guide_src/source/changelogs/index.rst';
+$newChangelog   = "./docs/changelogs/v{$newVersion}.md";
+$changelogIndex = './docs/changelogs/index.md';
 
 if ($isMinorUpdate) {
-    copy('./admin/next-changelog-minor.rst', $newChangelog);
+    copy('./admin/next-changelog-minor.md', $newChangelog);
 } else {
-    copy('./admin/next-changelog-patch.rst', $newChangelog);
+    copy('./admin/next-changelog-patch.md', $newChangelog);
 }
 
 // Replace version in CodeIgniter.php to {version}-dev.
@@ -54,46 +54,42 @@ function replace_file_content(string $path, string $pattern, string $replace): v
     "public const CI_VERSION = '{$newVersion}-dev';",
 );
 
-// Add changelog to index.rst.
+// Add changelog to the index, newest first.
 replace_file_content(
     $changelogIndex,
-    '/\.\. toctree::\n    :titlesonly:\n/u',
-    ".. toctree::\n    :titlesonly:\n\n    v{$newVersion}",
+    '/^(See all the changes\.\n\n)/mu',
+    "\$1- [Version {$newVersion}](v{$newVersion}.md)\n",
 );
 
 // Replace {version}
-$underline = str_repeat('#', mb_strlen("Version {$newVersion}"));
-replace_file_content(
-    $newChangelog,
-    '/#################\nVersion {version}\n#################/u',
-    "{$underline}\nVersion {$newVersion}\n{$underline}",
-);
 replace_file_content($newChangelog, '/{version}/u', $newVersion);
 
 // Copy upgrading
 $versionWithoutDots = str_replace('.', '', $newVersion);
-$newUpgrading       = "./user_guide_src/source/installation/upgrade_{$versionWithoutDots}.rst";
-$upgradingIndex     = './user_guide_src/source/installation/upgrading.rst';
-copy('./admin/next-upgrading-guide.rst', $newUpgrading);
+$newUpgrading       = "./docs/installation/upgrade_{$versionWithoutDots}.md";
+$upgradingIndex     = './docs/installation/upgrading.md';
+copy('./admin/next-upgrading-guide.md', $newUpgrading);
 
-// Add upgrading to upgrading.rst.
+// Add upgrading to the index, right after the backward compatibility notes.
 replace_file_content(
     $upgradingIndex,
-    '/    backward_compatibility_notes\n/u',
-    "    backward_compatibility_notes\n\n    upgrade_{$versionWithoutDots}",
+    '/^(- \[Backward Compatibility Notes\]\(backward_compatibility_notes\.md\)\n)/mu',
+    "\$1- [Upgrading from {$currentVersion} to {$newVersion}](upgrade_{$versionWithoutDots}.md)\n",
 );
 
 // Replace {version}
-$underline = str_repeat('#', mb_strlen("Upgrading from {$currentVersion} to {$newVersion}"));
 replace_file_content(
     $newUpgrading,
-    '/##############################\nUpgrading from {version} to {version}\n##############################/u',
-    "{$underline}\nUpgrading from {$currentVersion} to {$newVersion}\n{$underline}",
+    '/^# Upgrading from {version} to {version}$/mu',
+    "# Upgrading from {$currentVersion} to {$newVersion}",
 );
 
+// Add both pages to the nav.
+system('php ./admin/update-docs-nav.php');
+
 if (! in_array('--dry-run', $argv, true)) {
     system('git add ./system/CodeIgniter.php');
     system("git add {$newChangelog} {$changelogIndex}");
-    system("git add {$newUpgrading} {$upgradingIndex}");
+    system("git add {$newUpgrading} {$upgradingIndex} ./docs/.nav.yml");
     system("git commit -m \"docs: add changelog and upgrade for v{$newVersion}\"");
 }

admin/generate-changelog.php

@@ -2,14 +2,6 @@
 
 declare(strict_types=1);
 
-/**
- * Generates the CHANGELOG.md entry for a new release from GitHub's
- * auto-generated release notes and prepends it to CHANGELOG.md.
- *
- * Requires the authenticated GitHub CLI (`gh`).
- *
- * Usage: php admin/generate-changelog.php <version> [--dry-run]
- */
 chdir(__DIR__ . '/..');
 
 $args    = array_slice($argv, 1);
@@ -99,13 +91,13 @@
 // Extracts the security fixes from the SECURITY section of the detailed
 // changelog, if any. These come from security advisories, not from PRs, so
 // they are not part of the generated release notes.
-$rstPath  = "./user_guide_src/source/changelogs/v{$version}.rst";
-$security = '';
+$detailedPath = "./docs/changelogs/v{$version}.md";
+$security     = '';
 
-if (is_file($rstPath)) {
-    $rst = file_get_contents($rstPath);
+if (is_file($detailedPath)) {
+    $detailed = file_get_contents($detailedPath);
 
-    if (preg_match('/^\*+\nSECURITY\n\*+\n(.*?)(?=^\*+$|\z)/msu', $rst, $matches) === 1) {
+    if (preg_match('/^## SECURITY\n(.*?)(?=^## |\z)/msu', $detailed, $matches) === 1) {
         $security = trim($matches[1], "\n");
         $security = preg_replace('/^- /mu', '* ', $security);
     }

admin/next-changelog-minor.md

@@ -0,0 +1,49 @@
+# Version {version}
+
+Release Date: Unreleased
+
+**{version} release of CodeIgniter4**
+
+## Highlights
+
+- TBD
+
+## BREAKING
+
+### Behavior Changes
+
+### Interface Changes
+
+### Method Signature Changes
+
+## Enhancements
+
+### Commands
+
+### Testing
+
+### Database
+
+#### Query Builder
+
+#### Forge
+
+#### Others
+
+### Model
+
+### Libraries
+
+### Helpers and Functions
+
+### Others
+
+## Message Changes
+
+## Changes
+
+## Deprecations
+
+## Bugs Fixed
+
+See the repo's [CHANGELOG.md](https://github.com/codeigniter4/CodeIgniter4/blob/develop/CHANGELOG.md) for a complete list of bugs fixed.

admin/next-changelog-patch.md

@@ -0,0 +1,17 @@
+# Version {version}
+
+Release Date: Unreleased
+
+**{version} release of CodeIgniter4**
+
+## BREAKING
+
+## Message Changes
+
+## Changes
+
+## Deprecations
+
+## Bugs Fixed
+
+See the repo's [CHANGELOG.md](https://github.com/codeigniter4/CodeIgniter4/blob/develop/CHANGELOG.md) for a complete list of bugs fixed.

admin/next-upgrading-guide.md

@@ -0,0 +1,34 @@
+# Upgrading from {version} to {version}
+
+Please refer to the upgrade instructions corresponding to your installation method.
+
+- [Composer Installation App Starter Upgrading](installing_composer.md#upgrading)
+- [Composer Installation Adding CodeIgniter4 to an Existing Project Upgrading](installing_composer.md#upgrading_1)
+- [Manual Installation Upgrading](installing_manual.md#upgrading)
+
+## Mandatory File Changes
+
+## Breaking Changes
+
+## Breaking Enhancements
+
+## Project Files
+
+Some files in the **project space** (root, app, public, writable) received updates. Due to these files being outside of the **system** scope they will not be changed without your intervention.
+
+!!! note "Note"
+    There are some third-party CodeIgniter modules available to assist with merging changes to the project space: [Explore on Packagist](https://packagist.org/explore/?query=codeigniter4%20updates).
+
+### Content Changes
+
+The following files received significant changes (including deprecations or visual adjustments) and it is recommended that you merge the updated versions with your application:
+
+#### Config
+
+- @TODO
+
+### All Changes
+
+This is a list of all files in the **project space** that received changes; many will be simple comments or formatting that have no effect on the runtime:
+
+- @TODO

admin/prepare-release.php

@@ -39,16 +39,11 @@ function replace_file_content(string $path, string $pattern, string $replace): v
     "public const CI_VERSION = '{$version}';",
 );
 
-// Updates version number in "conf.py".
+// Updates the minor version in the title of the changelog index.
 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}'",
+    './docs/changelogs/index.md',
+    '/^## Version .*/mu',
+    "## Version {$minor}",
 );
 
 // Updates version number in "phpdoc.dist.xml".
@@ -66,7 +61,7 @@ function replace_file_content(string $path, string $pattern, string $replace): v
 // Updates release date in changelogs.
 $date = date('F j, Y');
 replace_file_content(
-    "./user_guide_src/source/changelogs/v{$version}.rst",
+    "./docs/changelogs/v{$version}.md",
     '/^Release Date: .*/mu',
     "Release Date: {$date}",
 );

admin/update-upgrade-guide.php

@@ -58,7 +58,7 @@ function bullets(array $items): string
 $version = $params[0];
 $dryRun  = in_array('--dry-run', $options, true);
 
-$upgradePath = sprintf('./user_guide_src/source/installation/upgrade_%s.rst', str_replace('.', '', $version));
+$upgradePath = sprintf('./docs/installation/upgrade_%s.md', str_replace('.', '', $version));
 
 if (! is_file($upgradePath)) {
     echo sprintf("%s is not found. Run \"php admin/create-new-changelog.php\" first.\n", $upgradePath);
@@ -83,11 +83,13 @@ function bullets(array $items): string
     ':!admin/',
     ':!changelogs/',
     ':!contributing/',
+    ':!docs/',
     ':!system/',
     ':!tests/',
     ':!user_guide_src/',
     ':!utils/',
     ':!.*',
+    ':!mkdocs.yml',
     ':!*.md',
     ':!*.json',
     ':!*.xml',
@@ -160,21 +162,21 @@ function bullets(array $items): string
     : bullets($allChanges);
 
 if ($dryRun) {
-    echo "\nConfig\n------\n\n{$configContent}\n";
-    echo "\nAll Changes\n===========\n\n{$allChangesContent}\n";
+    echo "\n#### Config\n\n{$configContent}\n";
+    echo "\n### All Changes\n\n{$allChangesContent}\n";
 
     exit(0);
 }
 
-$rst = file_get_contents($upgradePath);
+$markdown = file_get_contents($upgradePath);
 
 // Fills the "Config" section, only if it still has the placeholder. Entries
 // may have been added ahead of time for changes that need discussion, and
 // those must not be overwritten.
-if (preg_match('/^Config\n------\n\n(.*?)(?=^[^\s-][^\n]*\n(?:-+|=+)$|\z)/msu', $rst, $matches) !== 1) {
+if (preg_match('/^#### Config\n\n(.*?)(?=^#{1,4} |\z)/msu', $markdown, $matches) !== 1) {
     echo "Could not find the \"Config\" section in {$upgradePath}. Update it manually.\n";
 } elseif (trim($matches[1]) === '- @TODO') {
-    $rst = str_replace("Config\n------\n\n{$matches[1]}", "Config\n------\n\n{$configContent}\n\n", $rst);
+    $markdown = str_replace("#### Config\n\n{$matches[1]}", "#### Config\n\n{$configContent}\n\n", $markdown);
 
     echo "The \"Config\" section was updated. Add notes to each entry as needed.\n";
 } else {
@@ -195,8 +197,8 @@ function bullets(array $items): string
 }
 
 // Fills the "All Changes" section, replacing any previous list.
-$pattern = '/^(All Changes\n===========\n\n.*?:\n\n)(.*?)(?=^\*+$|\z)/msu';
-$updated = preg_replace($pattern, "\$1{$allChangesContent}\n", $rst, 1, $count);
+$pattern = '/^(### All Changes\n\n.*?:\n\n)(.*?)(?=^#{1,3} |\z)/msu';
+$updated = preg_replace($pattern, "\$1{$allChangesContent}\n", $markdown, 1, $count);
 
 if ($count !== 1) {
     echo "Could not find the \"All Changes\" section in {$upgradePath}. Update it manually.\n";