Skip to content

Commit

Permalink
Auto-sync vendor assets & Hugo module versions + copyedits to README …
Browse files Browse the repository at this point in the history
…and CONTRIBUTING (#1733)
  • Loading branch information
chalin committed Nov 12, 2023
1 parent c36c727 commit 1966f96
Show file tree
Hide file tree
Showing 10 changed files with 89 additions and 29 deletions.
30 changes: 14 additions & 16 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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/).
Expand All @@ -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.
Expand All @@ -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.

Expand Down
13 changes: 7 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
5 changes: 5 additions & 0 deletions assets/_vendor/README.md
Original file line number Diff line number Diff line change
@@ -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.
File renamed without changes.
2 changes: 0 additions & 2 deletions assets/bootstrap/README.txt

This file was deleted.

3 changes: 0 additions & 3 deletions assets/bootstrap/scss/_vendor/README.txt

This file was deleted.

2 changes: 2 additions & 0 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion hugo.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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",
Expand Down
56 changes: 56 additions & 0 deletions tools/getHugoModules/index.mjs
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 1966f96

Please sign in to comment.