From 6d751420bd1a54b4707071aa4a5dc8db615c0fda Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 30 Jun 2022 14:32:55 -0400 Subject: [PATCH] Release 0.4.0 preparation (#1078) --- CHANGELOG.md | 21 +++++-- CONTRIBUTING.md | 61 ++++++++++--------- go.mod | 2 +- package.json | 2 +- .../Docsy-As-Module/start-from-scratch.md | 8 +-- .../docs/Updating/Convert-site-to-module.md | 20 +++--- .../en/docs/Updating/Updating-hugo-module.md | 4 +- 7 files changed, 65 insertions(+), 53 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f911ede274..0c0cfcd873 100644 --- a/CHANGELOG.md +++ b/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,6 +47,8 @@ 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 @@ -52,10 +56,6 @@ For a list of issues targeted for the next release, see the [22Q2][] milestone. 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f4ea181a6a..78088bdf10 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/go.mod b/go.mod index c071e84b60..136e5965c1 100644 --- a/go.mod +++ b/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 ) diff --git a/package.json b/package.json index 4ef63fed6a..067f40edc5 100644 --- a/package.json +++ b/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 &&", diff --git a/userguide/content/en/docs/Get started/Docsy-As-Module/start-from-scratch.md b/userguide/content/en/docs/Get started/Docsy-As-Module/start-from-scratch.md index 117a364646..6806dcd017 100644 --- a/userguide/content/en/docs/Get started/Docsy-As-Module/start-from-scratch.md +++ b/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 <}} 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 <}} 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,7 +213,7 @@ 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 @@ -221,13 +221,13 @@ 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" diff --git a/userguide/content/en/docs/Updating/Updating-hugo-module.md b/userguide/content/en/docs/Updating/Updating-hugo-module.md index db37811385..c3f40477e3 100644 --- a/userguide/content/en/docs/Updating/Updating-hugo-module.md +++ b/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: