diff --git a/.markdown-link-check.json b/.markdown-link-check.json new file mode 100644 index 0000000000..0d310490b4 --- /dev/null +++ b/.markdown-link-check.json @@ -0,0 +1,10 @@ +{ + "ignorePatterns": [ + { + "pattern": "^http://localhost" + } + ], + "timeout": "3s", + "retryOn429": true, + "aliveStatusCodes": [200, 206] +} diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000000..54ed1b8a29 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,5 @@ +.editorconfig +.gitignore +.nvmrc +.prettierignore +.s3deploy.yml diff --git a/.prettierrc.json b/.prettierrc.json index b7741bb100..4ecfc6442a 100644 --- a/.prettierrc.json +++ b/.prettierrc.json @@ -1,5 +1,5 @@ { - "semi": true, - "singleQuote": true, - "tabWidth": 4 + "proseWrap": "always", + "semi": true, + "singleQuote": true } diff --git a/.vscode/cspell.json b/.vscode/cspell.json index ea5585c098..d3389d0e02 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -1,10 +1,6 @@ // For settings, see https://www.streetsidesoftware.com/vscode-spell-checker/docs/configuration/ { - "version": "0.2", - "caseSensitive": true, - "words": [ - "Docsy", - "shortcode", - "shortcodes" - ] + "version": "0.2", + "caseSensitive": true, + "words": ["Docsy", "shortcode", "shortcodes"] } diff --git a/CHANGELOG.md b/CHANGELOG.md index a70c9e2f9b..5c20cd3581 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ notes][releases]. Useful links: - [Releases][] & [tags][]. Jump to the [latest][] release. -- [23Q3][] milestone +- [23Q4][] milestone ## [0.8.0][0.x.y] - next major release (unpublished yet) @@ -23,20 +23,22 @@ For the full list of this release's changes, see the [release notes][0.x.y]. **Other changes**: -## [0.7.2][0.x.y] - next release (unpublished yet) +## [0.7.2][] -For the full list of this release's changes, see the [release notes][0.x.y]. - -**New**: +For the full list of this release's changes, see the [0.7.2 release +notes][0.7.2]. We mention one noteworthy change here: - **Algolia** - [#1651] DocSearch fixed for mobile and for sites with two search boxes (in the top and left navs). - [#1662] DocSearch is supported by Docsy through site config. - For details, see [Algolia DocSearch]. +- **Tabpane** shortcode: some improvements, with more to come; for details, see + [#1641]. [#1651]: https://github.com/google/docsy/pull/1651 [#1662]: https://github.com/google/docsy/pull/1662 +[#1641]: https://github.com/google/docsy/issues/1641 [Algolia DocSearch]: https://www.docsy.dev/docs/adding-content/search/#algolia-docsearch @@ -287,6 +289,7 @@ For the full list of this release's changes, see the [release notes][0.x.y]. [@deining]: https://github.com/deining [@lisafc]: https://github.com/LisaFC +[0.7.2]: https://github.com/google/docsy/releases/v0.7.2 [0.7.1]: https://github.com/google/docsy/releases/v0.7.1 [0.7.0]: https://github.com/google/docsy/releases/v0.7.0 [0.6.0]: https://github.com/google/docsy/releases/v0.6.0 @@ -296,7 +299,7 @@ For the full list of this release's changes, see the [release notes][0.x.y]. [0.3.0]: https://github.com/google/docsy/releases/v0.3.0 [0.2.0]: https://github.com/google/docsy/releases/v0.2.0 [0.x.y]: #changelog -[23q3]: https://github.com/google/docsy/milestone/8 +[23q4]: https://github.com/google/docsy/milestone/9 [hugo modules]: https://gohugo.io/hugo-modules/ [latest]: https://github.com/google/docsy/releases/latest [releases]: https://github.com/google/docsy/releases diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 82ccce057c..c1961097dc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ - + # How to Contribute @@ -31,7 +31,10 @@ This project follows ## Student contributions -Docsy welcomes contributions from students. However, we cannot guarantee that PRs will be merged within any specific timeframe. We ask that instructors *not* create assignments requiring students to have PRs merged into the project. We will not merge PRs solely to satisfy any class assignments. +Docsy welcomes contributions from students. However, we cannot guarantee that +PRs will be merged within any specific time frame. We ask that instructors _not_ +create assignments requiring students to have PRs merged into the project. We +will not merge PRs solely to satisfy any class assignments. ## How to contribute @@ -39,24 +42,26 @@ See the [contribution guidelines][] in the Docsy user guide. ## Publishing a release -These notes are WIP for creating a release (v0.X.Y) from a local copy of the +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. -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 using - the section template at the end of the file. (Note that change details are - autogenerated by GitHub in a later step.) -3. Update module and package versions: - - Update the version of `docsy/dependencies` in [go.mod](go.mod) to v0.X.Y. - - Update the NPM package version in [package.json](package.json) to 0.X.Y. -4. Update the Docsy `version` in [userguide/hugo.toml][] 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. Ensure that you're: - - On the default branch +1. **Change directory** to your local Docsy repo. +2. **Create or update a [CHANGELOG](CHANGELOG.md) entry** for v0.X.Y. The + section should provide 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 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 + preparation". +5. **Get PR approved and merged**. +6. **Pull in `main`** to get the last PR. +7. **Ensure** that you're: + - On the default branch, `main` - At the commit that you want to tag as the next release (usually `@HEAD`). -7. Create the tags for v0.X.Y (we currently need two): +8. **Create tags** for v0.X.Y (we currently need two): ```sh REL=v0.X.Y @@ -64,7 +69,7 @@ repo. git tag dependencies/$REL ``` -8. Push the new tags to the main repo (which is named `upstream` in the +9. **Push the new tags** to the main repo (which is named `upstream` in the following setup): ```console @@ -74,8 +79,7 @@ repo. * [new tag] dependencies/v0.X.Y -> dependencies/v0.X.Y ``` -9. Use the GitHub [Draft a new release][] feature, filling in the fields as - follows: +10. **[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. @@ -96,8 +100,27 @@ repo. - Remove the "New contributors" autogenerated text (if present) since we don't publish that as part of our release notes. - Select **Create a discussion for this release**. - - Click **Publish 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 + so, get fixes submitted, reviewed and approved. Then publish a dot release: + go back to step 1. + +## Post-release followup + +Assuming that Docsy release v0.X.Y has been successfully deployed and use by at +least one downstream project, then perform the following actions before any +further changes are merged into the default branch: + +1. Set `version` in [package.json](package.json) to the next planned (or the + next dot) release with a dev suffix, such as `v0.X.Z-dev.0-unreleased`. +2. (Optional) Run `hugo mod get`. +3. **Submit a PR with your changes**, using a title like "Set NPM package + version to next unreleased dev". +4. **Get PR approved and merged**. [contribution guidelines]: https://www.docsy.dev/docs/contribution-guidelines/ [Draft a new release]: https://github.com/google/docsy/releases/new -[userguide/hugo.toml]: userguide/hugo.toml +[docsy-example]: https://github.com/google/docsy-example +[userguide/hugo.yaml]: userguide/hugo.yaml diff --git a/go.mod b/go.mod index 05a07738ca..de343757a8 100644 --- a/go.mod +++ b/go.mod @@ -4,6 +4,6 @@ go 1.12 require ( github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2 // indirect - github.com/google/docsy/dependencies v0.7.1 // indirect + github.com/google/docsy/dependencies v0.7.2 // indirect github.com/twbs/bootstrap v5.2.3+incompatible // indirect ) diff --git a/package.json b/package.json index 9cceffb174..e7b62713f6 100644 --- a/package.json +++ b/package.json @@ -1,18 +1,22 @@ { "name": "docsy", - "version": "0.7.2-dev.0-unreleased", + "version": "0.7.2", "repository": "github:google/docsy", "homepage": "https://www.docsy.dev", "license": "Apache-2.0", "scripts": { "_cd:docs": "cd userguide &&", + "_check:format": "npx prettier --check .??* *.md", "build:preview": "npm run cd:docs build:preview", "build:production": "npm run cd:docs build:production", "build": "npm run cd:docs build", "cd:docs": "npm run _cd:docs -- npm run", + "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)", + "check:links--md": "npx markdown-link-check --config .markdown-link-check.json *.md", "check:links:all": "npm run cd:docs check:links:all", "check:links": "npm run cd:docs check:links", "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}", "serve": "npm run cd:docs serve", "test": "npm run cd:docs test", @@ -20,9 +24,6 @@ "update:pkg:dep": "npm install --save-exact @fortawesome/fontawesome-free@latest bootstrap@latest" }, "spelling": "cSpell:ignore docsy hugo fortawesome fontawesome userguide ", - "prettier": { - "proseWrap": "always" - }, "dependencies": { "@fortawesome/fontawesome-free": "6.4.0", "bootstrap": "5.2.3" @@ -30,6 +31,10 @@ "devDependencies": { "hugo-extended": "0.120.3" }, + "optionalDependencies": { + "markdown-link-check": "^3.11.2", + "prettier": "^3.0.3" + }, "engines": { "node": ">=20" } diff --git a/userguide/hugo.yaml b/userguide/hugo.yaml index 9a0d39e8ea..0740d14514 100644 --- a/userguide/hugo.yaml +++ b/userguide/hugo.yaml @@ -54,7 +54,7 @@ params: privacy_policy: https://policies.google.com/privacy version_menu: Releases archived_version: false - version: 0.7.1 + version: 0.7.2 url_latest_version: https://example.com github_repo: https://github.com/google/docsy github_project_repo: https://github.com/google/docsy diff --git a/userguide/package.json b/userguide/package.json index 12f8928769..0925475578 100644 --- a/userguide/package.json +++ b/userguide/package.json @@ -23,7 +23,7 @@ "update:pkg:dep": "npm install --save-dev autoprefixer@latest postcss-cli@latest" }, "devDependencies": { - "autoprefixer": "^10.4.14", + "autoprefixer": "^10.4.16", "postcss-cli": "^10.1.0" } }