From 86c88fc27b4e941d0455c38503c8572b9b5d3593 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 10 Nov 2023 15:59:14 -0500 Subject: [PATCH 1/7] Auto-sync vendor assets & module versions --- assets/_vendor/README.md | 5 +++++ .../scss/_vendor => _vendor/bootstrap/scss}/_rfs.scss | 0 assets/bootstrap/README.txt | 2 -- assets/bootstrap/scss/_vendor/README.txt | 3 --- hugo.yaml | 2 +- package.json | 4 +++- 6 files changed, 9 insertions(+), 7 deletions(-) create mode 100644 assets/_vendor/README.md rename assets/{bootstrap/scss/_vendor => _vendor/bootstrap/scss}/_rfs.scss (100%) delete mode 100644 assets/bootstrap/README.txt delete mode 100644 assets/bootstrap/scss/_vendor/README.txt diff --git a/assets/_vendor/README.md b/assets/_vendor/README.md new file mode 100644 index 0000000000..ab3d72f3e4 --- /dev/null +++ b/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 . + +DO NOT EDIT or manually override the files in this folder. They are +automatically synchronized as installation time. diff --git a/assets/bootstrap/scss/_vendor/_rfs.scss b/assets/_vendor/bootstrap/scss/_rfs.scss similarity index 100% rename from assets/bootstrap/scss/_vendor/_rfs.scss rename to assets/_vendor/bootstrap/scss/_rfs.scss diff --git a/assets/bootstrap/README.txt b/assets/bootstrap/README.txt deleted file mode 100644 index eb9a64e177..0000000000 --- a/assets/bootstrap/README.txt +++ /dev/null @@ -1,2 +0,0 @@ -This folder was added in order to work around a known bug in Go’s module management. -For details, please refer to: https://github.com/golang/go/issues/37397 diff --git a/assets/bootstrap/scss/_vendor/README.txt b/assets/bootstrap/scss/_vendor/README.txt deleted file mode 100644 index bbc3d024e1..0000000000 --- a/assets/bootstrap/scss/_vendor/README.txt +++ /dev/null @@ -1,3 +0,0 @@ -This file belongs to bootstrap framework: - -https://raw.githubusercontent.com/twbs/bootstrap/v4.6.1/scss/vendor/_rfs.scss \ No newline at end of file diff --git a/hugo.yaml b/hugo.yaml index f92c273bb5..3930bcf3ef 100644 --- a/hugo.yaml +++ b/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 diff --git a/package.json b/package.json index 1fc2ad1184..f75e3d00b6 100644 --- a/package.json +++ b/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", @@ -18,7 +20,7 @@ "docs-install": "npm run _cd:docs -- npm install", "fix:format": "npm run _check:format -- --write", "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", From ae7e25c8ee26ac0f047c1cb22d2e4a7b223c4de1 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 10 Nov 2023 16:39:58 -0500 Subject: [PATCH 2/7] Update index.mjs --- CONTRIBUTING.md | 30 +++++++++++++-------------- README.md | 13 ++++++------ go.mod | 2 ++ package.json | 3 ++- tools/getHugoModules/index.mjs | 38 ++++++++++++++++++++++++++++++++++ 5 files changed, 63 insertions(+), 23 deletions(-) create mode 100644 tools/getHugoModules/index.mjs diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5ad5444d76..8862b6a5e3 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index d9454199eb..26c5877c88 100644 --- a/README.md +++ b/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 diff --git a/go.mod b/go.mod index 4a5e22262d..b6597b752f 100644 --- a/go.mod +++ b/go.mod @@ -1,5 +1,7 @@ module github.com/google/docsy +// AUTO-GENERATED using `npm run write:go.mod` + go 1.12 require ( diff --git a/package.json b/package.json index f75e3d00b6..584e4922fd 100644 --- a/package.json +++ b/package.json @@ -24,7 +24,8 @@ "serve": "npm run cd:docs serve", "test": "npm run cd:docs test", "update:pkg:hugo": "npm install --save-exact -D hugo-extended@latest", - "update:pkg:dep": "npm install --save-exact @fortawesome/fontawesome-free@latest bootstrap@latest" + "update:pkg:dep": "npm install --save-exact @fortawesome/fontawesome-free@latest bootstrap@latest", + "write:go.mod": "node tools/updateHugoModule/index.mjs" }, "spelling": "cSpell:ignore docsy hugo fortawesome fontawesome userguide ", "dependencies": { diff --git a/tools/getHugoModules/index.mjs b/tools/getHugoModules/index.mjs new file mode 100644 index 0000000000..939ba27d9e --- /dev/null +++ b/tools/getHugoModules/index.mjs @@ -0,0 +1,38 @@ +// Run `hugo mod get` for Docsy module dependencies. +// Get dependencies versions from `package.json`. + +import fs from 'fs'; +import { execSync } from 'child_process'; + +function updateHugoModuleFromNpmPackage(npmPackageName, hugoModuleRefAtV) { + try { + // Read package.json + const packageJsonData = fs.readFileSync('package.json', 'utf8'); + const packageJson = JSON.parse(packageJsonData); + + // Extract package version + const packageVersion = packageJson.dependencies[npmPackageName]; + if (!packageVersion) { + throw new Error(`${npmPackageName} not found in dependencies`); + } + + // Execute the command + const command = `hugo mod get ${hugoModuleRefAtV}${packageVersion}`; + console.log(`Executing command: ${command}`); + const output = execSync(command); + + // Log output + console.log(output.toString()); + } catch (error) { + console.error('An error occurred:', error.message); + } +} + +const packagesToUpdate = [ + ['@fortawesome/fontawesome-free', 'github.com/FortAwesome/Font-Awesome@'], + ['bootstrap', 'github.com/twbs/bootstrap@v'] +]; + +packagesToUpdate.forEach(([npmPackageName, hugoModuleRefAtV]) => { + updateHugoModuleFromNpmPackage(npmPackageName, hugoModuleRefAtV); +}); From 72a94550237b1bb339f745ccf576087d3bc68df8 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 10 Nov 2023 16:45:20 -0500 Subject: [PATCH 3/7] Update index.mjs --- package.json | 4 ++-- tools/getHugoModules/index.mjs | 19 +++++++++++++------ 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/package.json b/package.json index 584e4922fd..9118b86154 100644 --- a/package.json +++ b/package.json @@ -19,13 +19,13 @@ "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": "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", - "update:pkg:dep": "npm install --save-exact @fortawesome/fontawesome-free@latest bootstrap@latest", - "write:go.mod": "node tools/updateHugoModule/index.mjs" + "update:pkg:dep": "npm install --save-exact @fortawesome/fontawesome-free@latest bootstrap@latest" }, "spelling": "cSpell:ignore docsy hugo fortawesome fontawesome userguide ", "dependencies": { diff --git a/tools/getHugoModules/index.mjs b/tools/getHugoModules/index.mjs index 939ba27d9e..30608e5cc6 100644 --- a/tools/getHugoModules/index.mjs +++ b/tools/getHugoModules/index.mjs @@ -1,15 +1,13 @@ -// Run `hugo mod get` for Docsy module dependencies. +// Runs `hugo mod get @` for Docsy module dependencies. // Get dependencies versions from `package.json`. import fs from 'fs'; import { execSync } from 'child_process'; +let packageJson; + function updateHugoModuleFromNpmPackage(npmPackageName, hugoModuleRefAtV) { try { - // Read package.json - const packageJsonData = fs.readFileSync('package.json', 'utf8'); - const packageJson = JSON.parse(packageJsonData); - // Extract package version const packageVersion = packageJson.dependencies[npmPackageName]; if (!packageVersion) { @@ -28,11 +26,20 @@ function updateHugoModuleFromNpmPackage(npmPackageName, hugoModuleRefAtV) { } } +try { + // Read package.json + const packageJsonData = fs.readFileSync('package.json', 'utf8'); + packageJson = JSON.parse(packageJsonData); +} catch (error) { + console.error('Failed to read package.json:', error.message); + process.exit(1); +} + const packagesToUpdate = [ ['@fortawesome/fontawesome-free', 'github.com/FortAwesome/Font-Awesome@'], ['bootstrap', 'github.com/twbs/bootstrap@v'] ]; packagesToUpdate.forEach(([npmPackageName, hugoModuleRefAtV]) => { - updateHugoModuleFromNpmPackage(npmPackageName, hugoModuleRefAtV); + updateHugoModuleFromNpmPackage(npmPackageName, hugoModuleRefAtV, packageJson); }); From 19d633f16108a0538ae8ffc263d2308ab68f7c26 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 10 Nov 2023 16:56:10 -0500 Subject: [PATCH 4/7] Update index.mjs --- go.mod | 4 ++-- tools/getHugoModules/index.mjs | 43 ++++++++++++++++++++-------------- 2 files changed, 27 insertions(+), 20 deletions(-) diff --git a/go.mod b/go.mod index b6597b752f..6dbcdc520f 100644 --- a/go.mod +++ b/go.mod @@ -1,9 +1,9 @@ module github.com/google/docsy -// AUTO-GENERATED using `npm run write:go.mod` - go 1.12 +// AUTO-GENERATED using `npm run write:go.mod` + require ( github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2 // indirect github.com/twbs/bootstrap v5.2.3+incompatible // indirect diff --git a/tools/getHugoModules/index.mjs b/tools/getHugoModules/index.mjs index 30608e5cc6..2e47d43c2f 100644 --- a/tools/getHugoModules/index.mjs +++ b/tools/getHugoModules/index.mjs @@ -4,42 +4,49 @@ import fs from 'fs'; import { execSync } from 'child_process'; -let packageJson; +const packageJson = readPackageJson(); +let exitStatus = 0; -function updateHugoModuleFromNpmPackage(npmPackageName, hugoModuleRefAtV) { +function getHugoModule(npmPkgNm, hugoModuleRefAtV) { try { - // Extract package version - const packageVersion = packageJson.dependencies[npmPackageName]; + // Extract module version + const packageVersion = packageJson.dependencies[npmPkgNm]; if (!packageVersion) { - throw new Error(`${npmPackageName} not found in dependencies`); + throw new Error(`${npmPkgNm} not found in dependencies`); } - // Execute the command const command = `hugo mod get ${hugoModuleRefAtV}${packageVersion}`; - console.log(`Executing command: ${command}`); + console.log(`> ${command}`); const output = execSync(command); - - // Log output console.log(output.toString()); } catch (error) { console.error('An error occurred:', error.message); + exitStatus = 1; } } -try { - // Read package.json - const packageJsonData = fs.readFileSync('package.json', 'utf8'); - packageJson = JSON.parse(packageJsonData); -} catch (error) { - console.error('Failed to read package.json:', error.message); - process.exit(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 exit = () => process.exit(exitStatus); + 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(([npmPackageName, hugoModuleRefAtV]) => { - updateHugoModuleFromNpmPackage(npmPackageName, hugoModuleRefAtV, packageJson); +packagesToUpdate.forEach(([npmPkgNm, hugoModuleRefAtV]) => { + getHugoModule(npmPkgNm, hugoModuleRefAtV, packageJson); }); + +exit(); + +// cSpell:ignore hugo twbs From 265d62f897bcac5444db83047f272f2b3184e3c7 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 10 Nov 2023 17:09:42 -0500 Subject: [PATCH 5/7] Update index.mjs --- tools/getHugoModules/index.mjs | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/tools/getHugoModules/index.mjs b/tools/getHugoModules/index.mjs index 2e47d43c2f..33312e8fb9 100644 --- a/tools/getHugoModules/index.mjs +++ b/tools/getHugoModules/index.mjs @@ -1,5 +1,5 @@ // Runs `hugo mod get @` for Docsy module dependencies. -// Get dependencies versions from `package.json`. +// It gets dependency versions from `package.json`. import fs from 'fs'; import { execSync } from 'child_process'; @@ -7,20 +7,26 @@ 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 packageVersion = packageJson.dependencies[npmPkgNm]; - if (!packageVersion) { + 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}${packageVersion}`; + const command = `hugo mod get ${hugoModuleRefAtV}${pkgVers}`; console.log(`> ${command}`); const output = execSync(command); console.log(output.toString()); } catch (error) { - console.error('An error occurred:', error.message); + console.error(`ERROR: ${error.message}\n`); exitStatus = 1; } } @@ -30,13 +36,11 @@ function readPackageJson() { const packageJsonData = fs.readFileSync('package.json', 'utf8'); return JSON.parse(packageJsonData); } catch (error) { - console.error('Failed to read package.json:', error.message); + console.error('FAILED to read package.json:', error.message); exit(); } } -const exit = () => process.exit(exitStatus); - const packagesToUpdate = [ // NPM package name, `Hugo module name@` optionally follow by `v` if needed ['@fortawesome/fontawesome-free', 'github.com/FortAwesome/Font-Awesome@'], From 71d8a52ae794be0808eca1bf44c8520938e8aaaa Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 10 Nov 2023 17:50:08 -0500 Subject: [PATCH 6/7] Fix comment --- go.mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/go.mod b/go.mod index 6dbcdc520f..23c43969f4 100644 --- a/go.mod +++ b/go.mod @@ -2,7 +2,7 @@ module github.com/google/docsy go 1.12 -// AUTO-GENERATED using `npm run write:go.mod` +// AUTO-GENERATED using `npm run get:hugo-modules` require ( github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2 // indirect From 21c776f341a2dd1abe386fa7d9f36034da4ed5e6 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 12 Nov 2023 17:32:10 -0500 Subject: [PATCH 7/7] Typo --- assets/_vendor/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/assets/_vendor/README.md b/assets/_vendor/README.md index ab3d72f3e4..730dba449c 100644 --- a/assets/_vendor/README.md +++ b/assets/_vendor/README.md @@ -2,4 +2,4 @@ This `_vendor` folder exists to work around a known bug in Go’s module management. For details, see . DO NOT EDIT or manually override the files in this folder. They are -automatically synchronized as installation time. +automatically synchronized at installation time.