Release 0.13.0 preparation (#2412)

Author: chalin

docsy.dev/content/en/blog/2025/0.13.0.md

@@ -6,7 +6,7 @@ author: >-
   [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)),
   for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc)
 message: Hello, world!
-body_class: release-highlights published-draft-post
+body_class: release-highlights # published-draft-post
 params:
   # Icon usage: {{% _param FA iconName color %}}
   BREAKING:

docsy.dev/content/en/site/changelog.md

@@ -54,8 +54,6 @@ See [semver].
 
 ## v0.13.0
 
-> **UNRELEASED: this planned version is still under development**
-
 **Resources**:
 
 - [Release 0.13.0 report and upgrade guide][0.13.0-blog]

docsy.dev/content/en/site/contributing.md

@@ -52,18 +52,22 @@ repo.
 
 1.  **Change directory** to your local Docsy repo.
 
-2.  **Create or update a [CHANGELOG] entry** for v0.X.Y. The section should
-    provide a brief summary of breaking changes using the section template at
-    the end of the file. (Note that change details are autogenerated by GitHub
-    in a later step.)
+2.  **Create or update a [CHANGELOG] entry** for v0.X.Y.
+    - The section should provide a brief summary of breaking changes using the
+      section template at the end of the file.
+    - Ensure to remove the UNRELEASED note.
+    - You'll create a new section for the next release in a later step.
 
-3.  Run `npm run fix`.
+3.  **Update the release report blog post** for v0.X.Y, if any. Remove draft
+    status.
+
+4.  Run `npm run fix`.
 
     > Note: This might update the version in `package.json` via `fix:version`,
     > but you can ignore this change since you'll be setting the version
     > explicitly in the next step.
 
-4.  **Update Docsy version** to v0.X.Y using the following from a (bash or zsh)
+5.  **Update Docsy version** to v0.X.Y using the following from a (bash or zsh)
     terminal:
 
     ```sh
@@ -74,13 +78,18 @@ repo.
     This updates both `version` keys in [package.json] and
     [docsy.dev/hugo.yaml].
 
-5.  Run `npm run ci:test`, which runs `ci:prepare` and more to ensure that,
+6.  Run `npm run ci:test`, which runs `ci:prepare` and more to ensure that,
     e.g., vendor assets and [go.mod] dependencies are up-to-date, etc.
 
-6.  **Submit a PR with your changes**, using a title like "Release v0.X.Y
-    preparation".
+7.  **Submit a PR with your changes**, using a title like "Release v0.X.Y
+    preparation". Use this command to create the PR via the web interface:
+
+    ```sh
+    gh pr create --web --title "Release $VERSION preparation" \
+      --body "- Contributes to #<ADD-RELEASE-PREP-ISSUE-HERE>"
+    ```
 
-7.  **Test the PR** branch from selected sites, and push any required
+8.  **Test the PR** branch from selected sites, and push any required
     adjustments.
     - If the test site uses Docsy as a Git submodule:
 
@@ -90,15 +99,15 @@ repo.
       git switch -t REPO/BRANCH-NAME # e.g. chalin/chalin-m25-0.13.0-prerelease
       ```
 
-8.  **Get PR approved and merged**.
+9.  **Get PR approved and merged**.
 
-9.  **Pull in `main`** to get the last PR.
+10. **Pull in `main`** to get the last PR.
 
-10. **Ensure** that you're:
+11. **Ensure** that you're:
     - On the default branch, `main`
     - At the commit that you want to tag as v0.X.Y
 
-11. **Create and push a tag** for v0.X.Y. Set the REL variable to the actual
+12. **Create and push a tag** for v0.X.Y. Set the REL variable to the actual
     version, or use the VERSION variable if you set it in the previous step.
 
     ```sh
@@ -112,7 +121,7 @@ repo.
     git tag $REL
     ```
 
-12. **Push the new tags** to the main remote (`origin` or `upstream` depending
+13. **Push the new tags** to the main remote (`origin` or `upstream` depending
     on your setup) as well as any secondary remotes, if any:
 
     ```console
@@ -121,7 +130,7 @@ repo.
     * [new tag]         v0.X.Y -> v0.X.Y
     ```
 
-13. **[Draft a new release][]** using GitHub web; fill in the fields as follows:
+14. **[Draft a new release][]** using GitHub web; fill in the fields as follows:
     - From the **release/tag dropdown**: Select the new release tag that you
       just pushed, v0.X.Y.
     - Set the **release title** to the release number (without the "v").
@@ -139,9 +148,9 @@ repo.
 
     - Select **Create a discussion for this release**.
 
-14. **Publish the release**: click _Publish release_.
-15. Test the release with a downstream project, such as [docsy-example].
-16. If you find issues, determine whether they need to be fixed immediately. If
+15. **Publish the release**: click _Publish release_.
+16. Test the release with a downstream project, such as [docsy-example].
+17. If you find issues, determine whether they need to be fixed immediately. If
     so, get fixes submitted, reviewed and approved. Then publish a dot release:
     go back to step 1.
 

docsy.dev/hugo.yaml

@@ -63,7 +63,7 @@ params:
     from_year: 2018
   privacy_policy: https://policies.google.com/privacy
   archived_version: false
-  version: 0.12.0
+  version: 0.13.0
   url_latest_version: https://example.com
   github_repo: https://github.com/google/docsy
   github_project_repo: https://github.com/google/docsy

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docsy",
-  "version": "0.13.0-dev+82-gec833d2",
+  "version": "0.13.0",
   "repository": "github:google/docsy",
   "homepage": "https://www.docsy.dev",
   "license": "Apache-2.0",
@@ -57,14 +57,14 @@
   },
   "devDependencies": {
     "cpy-cli": "^6.0.0",
-    "markdownlint-cli2": "^0.19.0",
+    "markdownlint-cli2": "^0.19.1",
     "prettier": "^3.6.2"
   },
   "config": {
     "hugo_version": "0.151.0"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "spelling": "cSpell:ignore docsy hugo fortawesome fontawesome onedark -"
 }

scripts/git/check-version.sh

@@ -11,6 +11,10 @@ if [ "$current_branch" = "main" ]; then
   exit 0
 fi
 
+if [ -n "${SKIP_VERSION_CHECK:-}" ]; then
+  exit 0
+fi
+
 output="$(npm run -s fix:version -- --silent 2>&1)"
 status=$?
 
@@ -31,5 +35,9 @@ if [ -n "$output" ]; then
   else
     echo 'Commit again if you are ok with the new ID.' >&2
   fi
+  echo >&2
+  echo "Don't want the version to be changed, maybe because this is a release" >&2
+  echo "branch? Set SKIP_VERSION_CHECK=1" >&2
+  echo >&2
   exit 1
 fi

tasks/0.13/commit-inventory.md

@@ -4,7 +4,7 @@ date: 2025-11-12
 cSpell:ignore: docsy
 ---
 
-> Report refreshed for commits through `f59cbb8` on `main`.
+> Report refreshed for commits through `52aa677` on `main`.
 
 Chronological list of [commits since v0.12.0][], broadly grouped into a few
 categories. We'll do a more detailed analysis and groupings when we create the
@@ -85,6 +85,11 @@ client projects.
 - `d3b5749` (`#2405`) Document `notoc`, and update TOC CSS class names
 - `f59cbb8` (`#2406`) [UX] Show left/right scroll indicators for the navbar on
   mobile
+- `39ee7ca` (`#2407`) Update changelog for navbar scroll indicators and notoc
+  docs
+- `15a3823` (`#2408`) Change link title from 'Documentation' to 'Docs'
+- `ec833d2` (`#2368`) [Blog] Release 0.13.0 report and upgrade guide
+- `52aa677` (`#2411`) Pre-0.13.0 release adjustments
 
 ## CI / tooling only
 

tasks/0.13/issue-mapping.md

@@ -4,7 +4,7 @@ date: 2025-11-12
 cSpell:ignore: docsy sidemenu FOUC katex mhchem sidenav
 ---
 
-> Report refreshed for commits through `f59cbb8` on `main`.
+> Report refreshed for commits through `52aa677` on `main`.
 
 Mapping [commits since v0.12.0][] to their originating issues (when known).
 
@@ -82,6 +82,10 @@ Mapping [commits since v0.12.0][] to their originating issues (when known).
 | `bd7f023` | `#2402` | Document i18n support for TOC labels, update task docs                                | `#2289`              | Documentation follow-up for TOC i18n                                     |
 | `d3b5749` | `#2405` | Document `notoc`, and update TOC CSS class names                                      | `#2289`              | Documentation for `notoc` parameter and TOC CSS class updates            |
 | `f59cbb8` | `#2406` | [UX] Show left/right scroll indicators for the navbar on mobile                       | —                    | UX improvement for mobile navbar scrolling                               |
+| `39ee7ca` | `#2407` | Update changelog for navbar scroll indicators and notoc docs                          | `#2406`, `#2405`     | Release documentation maintenance                                        |
+| `15a3823` | `#2408` | Change link title from 'Documentation' to 'Docs'                                      | —                    | Documentation terminology update                                         |
+| `ec833d2` | `#2368` | [Blog] Release 0.13.0 report and upgrade guide                                        | `#2266`              | Release blog post for 0.13.0                                             |
+| `52aa677` | `#2411` | Pre-0.13.0 release adjustments                                                        | `#2266`              | Final release preparation adjustments                                    |
 
 ## CI / tooling commits
 

tasks/0.13/release-wrapup.plan.md

@@ -1,7 +1,7 @@
 ---
 title: 0.13 Release wrapup plan
 date: 2025-11-12
-last-main-commit: f59cbb8
+last-main-commit: 52aa677
 cSpell:ignore: docsy
 ---
 
@@ -79,9 +79,8 @@ Repeat when new commits land on `main` do the following:
 - Take note of fixes and features that are not yet documented in the blog post
   or changelog.
 
-Report refreshed for commits through [f59cbb8] (includes mobile navbar scroll
-indicators, TOC i18n support, TOC style customization docs, KaTeX build-time
-rendering, dark mode enhancements, ScrollSpy fixes, and documentation updates).
+Report refreshed for commits through [52aa677] (includes release blog post,
+changelog updates, final release adjustments, and documentation improvements).
 
 ### 0.13.0 blog post
 
@@ -109,6 +108,5 @@ rendering, dark mode enhancements, ScrollSpy fixes, and documentation updates).
 
 [0.13.0 release report]: ../docsy.dev/content/en/blog/2025/0.13.0.md
 [0.13.0-changelog]: ../../docsy.dev/content/en/site/changelog/#v0130
-[f59cbb8]: https://github.com/google/docsy/commit/f59cbb8
 [v0.12.0...main]: https://github.com/google/docsy/compare/v0.12.0...main
 [0.13.0 blog post]: ../docsy.dev/content/en/blog/2025/0.13.0.md

tasks/0.13/wrapup-report.md

@@ -4,7 +4,7 @@ date: 2025-11-12
 cSpell:ignore: docsy
 ---
 
-> Report refreshed for commits through `f59cbb8` on `main`.
+> Report refreshed for commits through `52aa677` on `main`.
 
 ## Highlights since v0.12.0
 
@@ -83,22 +83,23 @@ Blog posts:
 
 Example site:
 
-- [ ] Update to adopt new alert shortcode and language menu defaults
-- [ ] Update to adopt new sidebar-root feature
+- [x] Update to adopt new alert shortcode - done via OTel website and Docsy
+      example site
+- [x] Update to adopt new sidebar-root feature - done via OTel website and Docsy
+      example site
 
 Verification, testing, and QA:
 
-- [ ] Sanity:
-  - [ ] Verify that the `docsy-example` site builds cleanly with the new
+- [x] Sanity:
+  - [x] Verify that the `docsy-example` site builds cleanly with the new
         dependencies
-  - [ ] Ensure other reference projects build cleanly with dependency
+  - [x] Ensure other reference projects build cleanly with dependency
         reorganizations
 
-- [ ] Testing & QA:
-  - [ ] Run visual regression/snapshot checks for navigation, ScrollSpy, and
+- [x] Testing & QA:
+  - [x] Run visual regression/snapshot checks for navigation, ScrollSpy, and
         dark-mode fixes
-  - [ ] Validate new locales/translations render correctly
-  - [ ] Review narrow-screen language menu screenshots and guidance
+  - [x] Review narrow-screen language menu screenshots and guidance
         (#2035/#2001)
 
 ## Release Report Blog