Add "publishing a release" notes and finalize Changelog (#1018)

CHANGELOG.md

@@ -4,13 +4,18 @@ Useful links: Docsy [releases][] & [tags][]. Jump to the [latest][] release.
 
 For a list of issues targeted for the next release, see the [22Q2][] milestone.
 
-## [0.3.0][] - next release (unpublished yet)
+## [0.4.0][] - next planned release (unpublished yet)
+
+TBC
+
+## [0.3.0][]
 
 **Breaking changes**:
 
-- Upgrade to [Algolia DocSearch v3](https://docsearch.algolia.com/docs/DocSearch-v3).
-  If your site uses the deprecated DocSearch v2, you must 
-  [update your DocSearch code](https://docsearch.algolia.com/docs/migrating-from-v2).
+- Upgrade to [Algolia DocSearch
+  v3](https://docsearch.algolia.com/docs/DocSearch-v3). If your site uses the
+  deprecated DocSearch v2, you must [update your DocSearch
+  code](https://docsearch.algolia.com/docs/migrating-from-v2).
 
 **Details**:
 
@@ -23,20 +28,20 @@ For a list of issues targeted for the next release, see the [22Q2][] milestone.
 - Add official Docsy support for [Hugo modules][]. Many thanks to the dedicated and
   patient efforts of [@deining][], who researched, experimented, and implemented
   this feature. Thanks to [@deining][] and [@LisaFC][] for the doc updates.
-  
+
   For details, see [Migrate to Hugo Modules](https://www.docsy.dev/docs/updating/convert-site-to-module/).
 
 **Details**:
 
 - See the [release notes][0.2.0]
 
-
 [@deining]: https://github.com/deining
-[@LisaFC]: https://github.com/LisaFC
+[@lisafc]: https://github.com/LisaFC
 [0.2.0]: https://github.com/google/docsy/releases/v0.2.0
 [0.3.0]: https://github.com/google/docsy/releases/v0.3.0
-[22Q2]: https://github.com/google/docsy/milestone/3
-[Hugo modules]: https://gohugo.io/hugo-modules/
+[0.4.0]: https://github.com/google/docsy/releases/v0.4.0
+[22q2]: https://github.com/google/docsy/milestone/3
+[hugo modules]: https://gohugo.io/hugo-modules/
 [latest]: https://github.com/google/docsy/releases/latest
 [releases]: https://github.com/google/docsy/releases
 [tags]: https://github.com/google/docsy/tags

CONTRIBUTING.md

@@ -32,3 +32,60 @@ This project follows
 See the [contribution
 guidelines](https://www.docsy.dev/docs/contribution-guidelines/)
 in the Docsy user guide.
+
+## Publishing a release
+
+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 and ensure that you're on a branch
+    and at the commit that you want to tag as the next release (usually
+    `@HEAD`).
+2.  Ensure that the [CHANGELOG](CHANGELOG.md) has a release summary entry for
+    v0.X.Y. If not, create one with a brief summary of breaking changes. (Change details are autogenerated by GitHub in a later step.)
+3.  Create the tags for v0.X.Y (we currently need two):
+
+    ```console
+    $ REL=v0.X.Y
+    $ git tag $REL
+    $ git tag dependencies/$REL
+    ```
+
+4.  Push the new tags to the main repo (which is named `upstream` in my setup)
+    either one by one or all together provided you have no other new tags
+    defined. The following illustrates the latter, and does a dry run first:
+
+    ```console
+    $ git push --dry-run --tags upstream
+    To https://github.com/google/docsy.git
+    * [new tag]         dependencies/v0.X.Y -> dependencies/v0.X.Y
+    * [new tag]         v0.X.Y -> v0.X.Y
+    ```
+
+    If only the two new tags are listed, drop the dry-run flag to push the tags.
+
+5.  Use the GitHub [Draft a new release][] feature, filling 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 tag name.
+    - Click "auto-generate release notes" to get the release details.
+    - Replace the auto-generated "## What's Changed" heading by the following:
+
+      ```markdown
+      ## Release summary
+
+      See, https://github.com/google/docsy/blob/main/CHANGELOG.md#0XY
+
+      ## Commit details
+      ```
+
+    - Replace the `0XY` anchor target above with a target appropriate for this
+      release.
+    - Remove the "New contributors" autogenerated text since we don't publish
+      that as part of our release notes.
+    - Select **Create a discussion for this release**.
+    - Click **Publish release**.
+
+[draft a new release]: https://github.com/google/docsy/releases/new