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/assets/_vendor/README.md b/assets/_vendor/README.md new file mode 100644 index 0000000000..730dba449c --- /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 at 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/go.mod b/go.mod index 4a5e22262d..23c43969f4 100644 --- a/go.mod +++ b/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 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..9118b86154 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", @@ -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", diff --git a/tools/getHugoModules/index.mjs b/tools/getHugoModules/index.mjs new file mode 100644 index 0000000000..33312e8fb9 --- /dev/null +++ b/tools/getHugoModules/index.mjs @@ -0,0 +1,56 @@ +// Runs `hugo mod get @` 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