Release 0.4.0 preparation (#1078)

CHANGELOG.md

@@ -4,7 +4,9 @@ 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.4.0][] - next planned release (unpublished yet)
+## [0.4.0][]
+
+For a full list of the changes to this release, see the [release notes][0.4.0].
 
 **Breaking changes**:
 
@@ -45,17 +47,15 @@ For a list of issues targeted for the next release, see the [22Q2][] milestone.
 
 ## [0.3.0][]
 
+For a full list of the changes to this release, see the [release notes][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).
 
-**Details**:
-
-- See the [release notes][0.3.0]
-
 ## [0.2.0][]
 
 **New**:
@@ -68,13 +68,22 @@ For a list of issues targeted for the next release, see the [22Q2][] milestone.
 
 **Details**:
 
-- See the [release notes][0.2.0]
+- For a full list of the changes to this release, see the [release notes][0.2.0]
+
+## [0.X.Y][] - next planned release (unpublished yet)
+
+For a full list of the changes to this release, see the [release notes][0.X.Y].
+
+**Breaking changes**:
+
+- ...
 
 [@deining]: https://github.com/deining
 [@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
 [0.4.0]: https://github.com/google/docsy/releases/v0.4.0
+[0.X.Y]: #
 [22q2]: https://github.com/google/docsy/milestone/3
 [hugo modules]: https://gohugo.io/hugo-modules/
 [latest]: https://github.com/google/docsy/releases/latest

CONTRIBUTING.md

@@ -38,23 +38,26 @@ in the Docsy user guide.
 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
+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. Update the Hugo module versions to v0.X.Y.
-4. Update the NPM package version in [package.json](package.json) to v0.X.Y.
-5.  Create the tags for v0.X.Y (we currently need two):
-
-    ```console
-    $ REL=v0.X.Y
-    $ git tag $REL
-    $ git tag dependencies/$REL
+    v0.X.Y. If not, create one with 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 the Hugo module versions to v0.X.Y.
+4.  Update the NPM package version in [package.json](package.json) to 0.X.Y.
+5.  Commit your changes, usually as a PR entitled "Release v0.X.Y preparation".
+    Once the PR is approved and merged, proceed with the remaining steps.
+6.  Create the tags for v0.X.Y (we currently need two):
+
+    ```sh
+    REL=v0.X.Y
+    git tag $REL
+    git tag dependencies/$REL
     ```
 
-6.  Push the new tags to the main repo (which is named `upstream` in my setup)
+7.  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:
 
@@ -67,28 +70,28 @@ repo.
 
     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
+8.  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 release number (without the "v").
-    - Click "auto-generate release notes" to get the release details.
-    - Replace the auto-generated "## What's Changed" heading by the following:
+    -   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").
+    -   Click "auto-generate release notes" to get the release details.
+    -   Replace the auto-generated "## What's Changed" heading by the following:
 
-      ```markdown
-      ## Release summary
+        ```markdown
+        ## Release summary
 
-      See, https://github.com/google/docsy/blob/main/CHANGELOG.md#0XY
+        See, https://github.com/google/docsy/blob/main/CHANGELOG.md#0XY
 
-      ## Commit details
-      ```
+        ## 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**.
+    -   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

go.mod

@@ -4,6 +4,6 @@ go 1.12
 
 require (
 	github.com/FortAwesome/Font-Awesome v0.0.0-20210804190922-7d3d774145ac // indirect
-	github.com/google/docsy/dependencies v0.3.0 // indirect
+	github.com/google/docsy/dependencies v0.4.0 // indirect
 	github.com/twbs/bootstrap v4.6.1+incompatible // indirect
 )

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docsy",
-  "version": "0.4.0-dev",
+  "version": "0.4.0",
   "repository": "github:google/docsy",
   "scripts": {
     "_cd:docs": "cd userguide &&",

userguide/content/en/docs/Get started/Docsy-As-Module/start-from-scratch.md

@@ -7,7 +7,7 @@ description: >
   Create a new Hugo site from scratch with Docsy as a Hugo Module
 ---
 
-The simplest approach to creating a Docsy site is [copying our example site](/docs/get-started/docsy-as-module/example-site-as-template/). However, if you're an experienced Hugo user or the site structure of our example site doesn't meet your needs, you may prefer to create a new site from scratch. With this option, you'll get Docsy look and feel, navigation, and other features, but you'll need to specify your own site structure. 
+The simplest approach to creating a Docsy site is [copying our example site](/docs/get-started/docsy-as-module/example-site-as-template/). However, if you're an experienced Hugo user or the site structure of our example site doesn't meet your needs, you may prefer to create a new site from scratch. With this option, you'll get Docsy look and feel, navigation, and other features, but you'll need to specify your own site structure.
 
 These instructions give you a minimum file structure for your site project only, so that you build and extend your actual site step by step. The first step is adding the Docsy theme as a [Hugo Module](https://gohugo.io/hugo-modules/) to your site. If needed, you can easily [update](/docs/updating/) the module to the latest revision from the Docsy GitHub repo.
 
@@ -21,7 +21,7 @@ At your command prompt, run the following:
 hugo new site my-new-site
 cd  my-new-site
 hugo mod init github.com/me/my-new-site
-hugo mod get github.com/google/docsy@v0.3.0
+hugo mod get github.com/google/docsy@v0.4.0
 cat >> config.toml <<EOL
 [module]
 proxy = "direct"
@@ -36,7 +36,7 @@ hugo server
 hugo new site my-new-site
 cd  my-new-site
 hugo mod init github.com/me/my-new-site
-hugo mod get github.com/google/docsy@v0.3.0
+hugo mod get github.com/google/docsy@v0.4.0
 (echo [module]^
 
 proxy = "direct"^
@@ -83,7 +83,7 @@ This creates two new files, `go.mod` for the module definitions and `go.sum` whi
 Next declare the Docsy theme module as a dependency for your site.
 
 ```bash
-hugo mod get github.com/google/docsy@v0.3.0
+hugo mod get github.com/google/docsy@v0.4.0
 ```
 
 This command adds the `docsy` theme module to your definition file `go.mod`.

userguide/content/en/docs/Updating/Convert-site-to-module.md

@@ -15,7 +15,7 @@ Run the following from the command line:
 {{< tab header="Unix shell" lang="Bash" >}}
 cd /path/to/my-existing-site
 hugo mod init github.com/me-at-github/my-existing-site
-hugo mod get github.com/google/docsy@v0.3.0
+hugo mod get github.com/google/docsy@v0.4.0
 sed -i '/theme = \["docsy"\]/d' config.toml
 cat >> config.toml <<EOL
 [module]
@@ -30,7 +30,7 @@ hugo server
 {{< tab header="Windows command line" lang="Batchfile" >}}
 cd  my-existing-site
 hugo mod init github.com/me-at-github/my-existing-site
-hugo mod get github.com/google/docsy@v0.3.0
+hugo mod get github.com/google/docsy@v0.4.0
 findstr /v /c:"theme = [\"docsy\"]" config.toml > config.toml.temp
 move /Y config.toml.temp config.toml
 (echo [module]^
@@ -70,7 +70,7 @@ This creates two new files, `go.mod` for the module definitions and `go.sum` whi
 Next declare the Docsy theme module as a dependency for your site.
 
 ```bash
-hugo mod get github.com/google/docsy@v0.3.0
+hugo mod get github.com/google/docsy@v0.4.0
 ```
 
 This command adds the `docsy` theme module to your definition file `go.mod`.
@@ -181,10 +181,10 @@ To make sure that your configuration settings are correct, run the command `hugo
 ```bash
 hugo mod graph
 hugo: collected modules in 1092 ms
-github.com/me/my-existing-site github.com/google/docsy@v0.3.0
-github.com/me/my-existing-site github.com/google/docsy/dependencies@v0.3.0
-github.com/google/docsy/dependencies@v0.3.0 github.com/twbs/bootstrap@v4.6.1+incompatible
-github.com/google/docsy/dependencies@v0.3.0 github.com/FortAwesome/Font-Awesome@v0.0.0-20210804190922-7d3d774145ac
+github.com/me/my-existing-site github.com/google/docsy@v0.4.0
+github.com/me/my-existing-site github.com/google/docsy/dependencies@v0.4.0
+github.com/google/docsy/dependencies@v0.4.0 github.com/twbs/bootstrap@v4.6.1+incompatible
+github.com/google/docsy/dependencies@v0.4.0 github.com/FortAwesome/Font-Awesome@v0.0.0-20210804190922-7d3d774145ac
 ```
 
 Make sure that three lines with dependencies `docsy`, `bootstrap` and `Font-Awesome` are listed. If not, please double check your config settings.
@@ -213,21 +213,21 @@ cd /path/to/my-existing-site
 
 ### Previous use of Docsy theme as git clone
 
-Simply remove the subdirectory `docsy` inside your `themes` directory: 
+Simply remove the subdirectory `docsy` inside your `themes` directory:
 
 ```bash
 rm -rf themes/docsy
 ```
 
 ### Previous use of Docsy theme as git submodule
 
-If your Docsy theme was installed as submodule, use git's `rm` subcommand to remove the subdirectory `docsy` inside your `themes` directory: 
+If your Docsy theme was installed as submodule, use git's `rm` subcommand to remove the subdirectory `docsy` inside your `themes` directory:
 
 ```bash
 git rm -rf themes/docsy
 ```
 
-You are now ready to commit your changes to your repository: 
+You are now ready to commit your changes to your repository:
 
 ```bash
 git commit -m "Removed docsy git submodule"

userguide/content/en/docs/Updating/Updating-hugo-module.md

@@ -24,10 +24,10 @@ Hugo automatically pulls in the latest theme version. That's it, your update is
 
 
 {{% alert title="Tip" %}}
-If you want to set your module to a certain version inside the docsy theme repo, simply specific the name of the tag representing this version (here: _v0.3.0_) when updating your theme:
+If you want to set your module to a certain version inside the docsy theme repo, simply specific the name of the tag representing this version (here: _v0.4.0_) when updating your theme:
 
 ```bash
-hugo mod get -u github.com/google/docsy@v0.3.0
+hugo mod get -u github.com/google/docsy@v0.4.0
 ```
 
 Instead of a version tag, you can also specify a commit hash inside the repo (here: _c7b9901e_) when updating your theme: