Auto-sync vendor assets & Hugo module versions + copyedits to README and CONTRIBUTING

CONTRIBUTING.md

@@ -5,7 +5,7 @@
 We'd love to accept your patches and contributions to this project. There are
 just a few small guidelines you need to follow.
 
-## Contributor License Agreement
+## Contributor License Agreement (CLA)
 
 Contributions to this project must be accompanied by a Contributor License
 Agreement. You (or your employer) retain the copyright to your contribution;
@@ -24,7 +24,7 @@ use GitHub pull requests for this purpose. Consult
 [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
 information on using pull requests.
 
-## Community Guidelines
+## Community Guidelines / Code of conduct
 
 This project follows
 [Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
@@ -51,35 +51,33 @@ repo.
     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:
-    - `github.com/google/docsy/dependencies` in [go.mod](go.mod)
     - `version` key in [package.json](package.json)
     - `version` key in [userguide/hugo.yaml][]
-4.  **Submit a PR with your changes**, using a title like "Release v0.X.Y
+4.  Run `npm install` to have vendor assets and [go.mod](go.mod) updated.
+5.  **Submit a PR with your changes**, using a title like "Release v0.X.Y
     preparation".
-5.  **Get PR approved and merged**.
-6.  **Pull in `main`** to get the last PR.
-7.  **Ensure** that you're:
+6.  **Get PR approved and merged**.
+7.  **Pull in `main`** to get the last PR.
+8.  **Ensure** that you're:
     - On the default branch, `main`
     - At the commit that you want to tag as v0.X.Y
-8.  **Create tags** for v0.X.Y (we currently need two):
+9.  **Create tags** for v0.X.Y:
 
     ```sh
     REL=v0.X.Y
     git tag $REL
-    git tag dependencies/$REL
     ```
 
-9.  **Push the new tags** to the main repo, which is named `upstream` in the
+10. **Push the new tags** to the main repo, which is named `upstream` in the
     following example:
 
     ```console
-    $ git push upstream $REL && git push upstream dependencies/$REL
+    $ git push upstream $REL
     ...
     * [new tag]         v0.X.Y -> v0.X.Y
-    * [new tag]         dependencies/v0.X.Y -> dependencies/v0.X.Y
     ```
 
-10. **[Draft a new release][]** using GitHub web; fill in the fields as follows:
+11. **[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.
@@ -99,9 +97,9 @@ repo.
       don't publish that as part of our release notes.
     - Select **Create a discussion for this release**.
 
-11. **Publish the release**: click _Publish release_.
-12. Test the release with a downstream project, such as [docsy-example].
-13. If you find issues, determine whether they need to be fixed immediately. If
+12. **Publish the release**: click _Publish release_.
+13. Test the release with a downstream project, such as [docsy-example].
+14. 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.
 

README.md

@@ -89,18 +89,19 @@ npm run serve
 
 ## Contributing
 
-Please read
-[CONTRIBUTING.md](https://github.com/google/docsy/blob/main/CONTRIBUTING.md) for
-details on our code of conduct, and the process for submitting pull requests to
-us. See also the list of
-[contributors](https://github.com/google/docsy/graphs/contributors) who
-participated in this project.
+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
+[contributors]!
 
 ## License
 
 This project is licensed under the Apache License 2.0 - see the
 [LICENSE.md](https://github.com/google/docsy/blob/main/LICENSE) file for details
 
+[code of conduct]:
+  https://github.com/google/.github/blob/master/CODE_OF_CONDUCT.md
+[CONTRIBUTING.md]: https://github.com/google/docsy/blob/main/CONTRIBUTING.md
+[contributors]: https://github.com/google/docsy/graphs/contributors
 [deploys]: https://app.netlify.com/sites/docsydocs/deploys
 [netlify]: https://netlify.com
 [releases]: https://github.com/google/docsy/releases

assets/_vendor/README.md

@@ -0,0 +1,5 @@
+This `_vendor` folder exists to work around a known bug in Go’s module
+management. For details, see <https://github.com/golang/go/issues/37397>.
+
+DO NOT EDIT or manually override the files in this folder. They are
+automatically synchronized at installation time.

go.mod

@@ -2,6 +2,8 @@ module github.com/google/docsy
 
 go 1.12
 
+// AUTO-GENERATED using `npm run get:hugo-modules`
+
 require (
 	github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2 // indirect
 	github.com/twbs/bootstrap v5.2.3+incompatible // indirect

hugo.yaml

@@ -44,7 +44,7 @@ module:
       target: static/webfonts
     # Mounts for module installations,
     # needed to work around a known bug in Go’s module management.
-    - source: assets/bootstrap/scss/_vendor
+    - source: assets/_vendor/bootstrap/scss/
       target: assets/vendor/bootstrap/scss/vendor
   imports:
     - path: github.com/twbs/bootstrap

package.json

@@ -7,6 +7,8 @@
   "scripts": {
     "_cd:docs": "cd userguide &&",
     "_check:format": "npx prettier --check .??* *.md",
+    "_mkdir:hugo-mod": "npx mkdirp ../github.com/FortAwesome/Font-Awesome ../github.com/twbs/bootstrap",
+    "_cp:bs-rfs": "cp -R node_modules/bootstrap/scss/vendor/* assets/_vendor/bootstrap/scss/",
     "build:preview": "npm run cd:docs build:preview",
     "build:production": "npm run cd:docs build:production",
     "build": "npm run cd:docs build",
@@ -17,8 +19,9 @@
     "check:links": "npm run cd:docs check:links",
     "docs-install": "npm run _cd:docs -- npm install",
     "fix:format": "npm run _check:format -- --write",
+    "get:hugo-modules": "node tools/getHugoModules/index.mjs",
     "get:submodule": "set -x && git submodule update --init ${DEPTH:- --depth 1}",
-    "postinstall": "npx mkdirp ../github.com/FortAwesome/Font-Awesome ../github.com/twbs/bootstrap",
+    "postinstall": "npm run _mkdir:hugo-mod && npm run _cp:bs-rfs",
     "serve": "npm run cd:docs serve",
     "test": "npm run cd:docs test",
     "update:pkg:hugo": "npm install --save-exact -D hugo-extended@latest",

tools/getHugoModules/index.mjs

@@ -0,0 +1,56 @@
+// Runs `hugo mod get <module>@<vers>` for Docsy module dependencies.
+// It gets dependency versions from `package.json`.
+
+import fs from 'fs';
+import { execSync } from 'child_process';
+
+const packageJson = readPackageJson();
+let exitStatus = 0;
+
+const exit = () => process.exit(exitStatus);
+
+function getHugoModule(npmPkgNm, hugoModuleRefAtV) {
+  try {
+    // Extract module version
+    const pkgVers = packageJson.dependencies[npmPkgNm];
+    if (!pkgVers) {
+      throw new Error(`${npmPkgNm} not found in dependencies`);
+    }
+    if (!/^\d/.test(pkgVers)) {
+      const msg = `${npmPkgNm} version must be exact (start with a number), not: ${pkgVers}`;
+      throw new Error(msg);
+    }
+
+    const command = `hugo mod get ${hugoModuleRefAtV}${pkgVers}`;
+    console.log(`> ${command}`);
+    const output = execSync(command);
+    console.log(output.toString());
+  } catch (error) {
+    console.error(`ERROR: ${error.message}\n`);
+    exitStatus = 1;
+  }
+}
+
+function readPackageJson() {
+  try {
+    const packageJsonData = fs.readFileSync('package.json', 'utf8');
+    return JSON.parse(packageJsonData);
+  } catch (error) {
+    console.error('FAILED to read package.json:', error.message);
+    exit();
+  }
+}
+
+const packagesToUpdate = [
+  // NPM package name, `Hugo module name@` optionally follow by `v` if needed
+  ['@fortawesome/fontawesome-free', 'github.com/FortAwesome/Font-Awesome@'],
+  ['bootstrap', 'github.com/twbs/bootstrap@v']
+];
+
+packagesToUpdate.forEach(([npmPkgNm, hugoModuleRefAtV]) => {
+  getHugoModule(npmPkgNm, hugoModuleRefAtV, packageJson);
+});
+
+exit();
+
+// cSpell:ignore hugo twbs