Set NPM package version to next unreleased dev & rel-doc tweaks (#1761)

Author: chalin

CHANGELOG.md

@@ -11,16 +11,31 @@ notes][releases].
 Useful links:
 
 - [Releases] & [tags]. Jump to the [latest] release.
-- [23Q4] milestone
+- Milestones: [23Q4], [24Q1]
 
-[23q4]: https://github.com/google/docsy/milestone/9
+[23Q4]: https://github.com/google/docsy/milestone/9
+[24Q1]: https://github.com/google/docsy/milestone/10
 [latest]: https://github.com/google/docsy/releases/latest
 [releases]: https://github.com/google/docsy/releases
 [tags]: https://github.com/google/docsy/tags
 
+## 0.8.1 or 0.9.0 - next planned release, WIP
+
+For the full list of changes, see the [0.x.y] release notes.
+
+**Breaking changes**:
+
+- ...
+
+**New**:
+
+**Other changes**:
+
+[0.x.y]: https://github.com/google/docsy/releases/latest?FIXME=v0.X.Y
+
 ## 0.8.0
 
-For the full list of changes, see the [release][0.8.0] notes.
+For the full list of changes, see the [0.8.0] release notes.
 
 **Breaking changes**:
 
@@ -45,7 +60,7 @@ For the full list of changes, see the [release][0.8.0] notes.
 [#1385]: https://github.com/google/docsy/issues/1385
 [#1726]: https://github.com/google/docsy/pull/1726
 [#1727]: https://github.com/google/docsy/pull/1727
-[0.8.0]: https://github.com/google/docsy/releases/latest?fixme=v0.8.0
+[0.8.0]: https://github.com/google/docsy/releases/v0.8.0
 [Docsy NPM install side-effect]:
   https://docsy.dev/docs/get-started/other-options/#docsy-npm-install-side-effect
 [Use Docsy as a Hugo Module]:
@@ -55,7 +70,7 @@ For the full list of changes, see the [release][0.8.0] notes.
 
 ## 0.7.2
 
-For the full list of changes, see the [release][0.7.2] notes. We mention some
+For the full list of changes, see the [0.7.2] release notes. We mention some
 noteworthy changes here:
 
 - **Algolia**
@@ -84,7 +99,7 @@ noteworthy changes here:
 
 ## 0.7.1
 
-For the full list of changes, see the [release][0.7.1] notes.
+For the full list of changes, see the [0.7.1] release notes.
 
 Followup changes to **Bootstrap (BS) 5.2 upgrade** ([#470]):
 
@@ -99,7 +114,7 @@ Followup changes to **Bootstrap (BS) 5.2 upgrade** ([#470]):
 
 ## 0.7.0
 
-For the full list of changes, see the [release][0.7.0] notes.
+For the full list of changes, see the [0.7.0] release notes.
 
 **New**:
 
@@ -162,7 +177,7 @@ For the full list of changes, see the [release][0.7.0] notes.
 
 ## 0.6.0
 
-For the full list of changes, see the [release][0.6.0] notes.
+For the full list of changes, see the [0.6.0] release notes.
 
 With this release we declare a feature freeze while we migrate to the newest
 Bootstrap version. See [the announcement][bs-announcement] for more information.
@@ -183,7 +198,7 @@ Bootstrap version. See [the announcement][bs-announcement] for more information.
 
 ## 0.5.1
 
-For the full list of changes, see the [release][0.5.1] notes. **BREAKING
+For the full list of changes, see the [0.5.1] release notes. **BREAKING
 CHANGES** are documented below.
 
 **After you update** your project's Docsy:
@@ -240,7 +255,7 @@ Unpublished.
 
 ## 0.4.0
 
-For the full list of changes, see the [release][0.4.0] notes. Potential
+For the full list of changes, see the [0.4.0] release notes. Potential
 **BREAKING CHANGES** are documented below.
 
 **After you update** your project's Docsy, run `npm install`.
@@ -296,7 +311,7 @@ Proceed as usual to build or serve your site.
 
 ## 0.3.0
 
-For the full list of changes, see the [release][0.3.0] notes.
+For the full list of changes, see the [0.3.0] release notes.
 
 **Breaking changes**:
 
@@ -315,7 +330,7 @@ For the full list of changes, see the [release][0.3.0] notes.
 
 ## 0.2.0
 
-For the full list of changes, see the [release][0.2.0] notes.
+For the full list of changes, see the [0.2.0] release notes.
 
 **New**:
 
@@ -332,11 +347,11 @@ For the full list of changes, see the [release][0.2.0] notes.
 [0.2.0]: https://github.com/google/docsy/releases/v0.2.0
 [hugo modules]: https://gohugo.io/hugo-modules/
 
-<!-- SECTION TEMPLATE ------------------------------------------------------
+<!-- ENTRY TEMPLATE ------------------------------------------------------
 
 ## 0.X.Y - next planned release (unpublished yet)
 
-For the full list of changes, see the [release][0.x.y] notes.
+For the full list of changes, see the [0.x.y] release notes.
 
 **Breaking changes**:
 
@@ -346,6 +361,6 @@ For the full list of changes, see the [release][0.x.y] notes.
 
 **Other changes**:
 
-[0.x.y]: https://github.com/google/docsy/releases/v0.X.Y-FIXME
+[0.x.y]: https://github.com/google/docsy/releases/latest?FIXME=v0.X.Y
 
 ---------------------------------------------------------------------------->

CONTRIBUTING.md

@@ -46,10 +46,10 @@ These notes are WIP for creating a **release (v0.X.Y)** from a local copy of the
 repo.
 
 1.  **Change directory** to your local Docsy repo.
-2.  **Create or update a [CHANGELOG](CHANGELOG.md) 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. (Note that change details are autogenerated by GitHub
+    in a later step.)
 3.  **Update Docsy version** to v0.X.Y for:
     - `version` key in [package.json](package.json)
     - `version` key in [userguide/hugo.yaml][]
@@ -94,8 +94,6 @@ repo.
       See, https://github.com/google/docsy/blob/main/CHANGELOG.md#0XY
       ```
 
-    - Remove the "New contributors" autogenerated text (if present) since we
-      don't publish that as part of our release notes.
     - Select **Create a discussion for this release**.
 
 12. **Publish the release**: click _Publish release_.
@@ -112,11 +110,17 @@ further changes are merged into the default branch:
 
 1. Set `version` in [package.json](package.json) to the next planned (or the
    next dot) release with a dev suffix, such as `v0.X.Z-dev.0-unreleased`.
-2. **Submit a PR with your changes**, using a title like "Set NPM package
+2. In the [CHANGELOG]:
+   - **Create a new entry** for the next release by copying the ENTRY TEMPLATE
+     at the end of the file.
+   - **Pin the 0.X.Y release URL**, which ends with `latest?FIXME=...`, to the
+     v0.X.Y release at `https://github.com/google/docsy/releases/v0.x.y`.
+3. **Submit a PR with your changes**, using a title like "Set NPM package
    version to next unreleased dev".
-3. **Get PR approved and merged**.
+4. **Get PR approved and merged**.
 
+[CHANGELOG]: CHANGELOG.md
 [contribution guidelines]: https://www.docsy.dev/docs/contribution-guidelines/
-[Draft a new release]: https://github.com/google/docsy/releases/new
 [docsy-example]: https://github.com/google/docsy-example
+[Draft a new release]: https://github.com/google/docsy/releases/new
 [userguide/hugo.yaml]: userguide/hugo.yaml

README.md

@@ -42,7 +42,7 @@ The following are basic prerequisites for using Docsy in your site:
 Any additional prerequisites depend on the
 [installation option](https://www.docsy.dev/docs/get-started/#installation-options)
 you choose. We recommend using Docsy as a Hugo module, which requires that you
-have the `go` language installed in addition to Hugo and PostCSS.
+have the Go language installed in addition to Hugo and PostCSS.
 
 For complete prerequisites and instructions, see our
 [Get started guides](https://www.docsy.dev/docs/get-started/).
@@ -89,8 +89,8 @@ npm run serve
 
 ## Contributing
 
-Read [CONTRIBUTING.md] for details on our [code of conduct], and the process for
-submitting pull requests to us. Thank you to all past, present, and future
+For details on our [code of conduct] and the process for submitting pull
+requests, see [CONTRIBUTING.md]. Thank you to all past, present, and future
 [contributors]!
 
 ## License

package.json

@@ -1,7 +1,6 @@
 {
   "name": "docsy",
-  "version": "0.8.0",
-  "version.next": "0.8.1-dev.0-unreleased",
+  "version": "0.8.1-dev.0-unreleased",
   "repository": "github:google/docsy",
   "homepage": "https://www.docsy.dev",
   "license": "Apache-2.0",
@@ -15,6 +14,7 @@
     "build:production": "npm run cd:docs build:production",
     "build": "npm run cd:docs build",
     "cd:docs": "npm run _cd:docs -- npm run",
+    "check": "npm run check:format && npm run check:links--md",
     "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
     "check:links--md": "npx markdown-link-check --config .markdown-link-check.json *.md",
     "check:links:all": "npm run cd:docs check:links:all",
@@ -30,7 +30,7 @@
     "preserve": "npm run _prebuild",
     "pretest": "npm run _prebuild",
     "serve": "npm run cd:docs serve",
-    "test": "npm run cd:docs test && npm run check:links--md",
+    "test": "npm run cd:docs test && npm run check",
     "update:pkg:dep": "npm install --save-exact @fortawesome/fontawesome-free@latest bootstrap@latest",
     "update:pkg:hugo": "npm install --save-exact -D hugo-extended@latest"
   },