Add notes on regular site maintenance. (#5637)

This commit is contained in:
Martin Taillefer 2019-11-12 09:42:29 -08:00 committed by GitHub
parent f20dae83ac
commit 472ac56ba8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 25 additions and 0 deletions

View File

@ -20,6 +20,7 @@ see the Istio [contribution guidelines](https://github.com/istio/community/blob/
- [Publishing content immediately](#publishing-content-immediately)
- [Creating a version](#creating-a-version)
- [Creating a patch release](#creating-a-patch-release)
- [Regular maintenance](#regular-maintenance)
## Editing and building
@ -165,3 +166,27 @@ you describe the changes in the release.
For the release note file, please look at existing files in the same location for example content and
layout.
## Regular maintenance
We have a number of checks in place to ensure a number of invariants are maintained in order to
help the site's overall quality. For example, we disallow checking in broken links and we do spell
checking. There are some things which are hard to systematically check through automation and instead
require a human to review on in a while to ensure everything's doing well.
It's a good idea to run through this list before every major release of the site:
- Ensure that references to the Istio repos on GitHub don't hardcode branch names. Search for any uses of `/release-1` or `/master`
throughout all the markdown files and replace those with {{< source_branch_name >}} instead, which produces a version-appropriate
branch name.
- Review the .spelling file for words thst shouldn't be in there. Type names in particular tend to creep in here. Type names should
not be in the dictionary and should instead be shown with `backticks`. Remove the entries from the dictionary and fix any spell
checking errors that emerge.
- Ensure proper capitalization. Document titles need to be fully capitalized (e.g. "This is a Valid Title"),
while section headings should use first letter capitalization only (e.g. "This is a valid heading").
- Ensure that preformatted text blocks that reference files from the Istio GitHub repos use the @@ syntax
to produce links to the content. See [here](https://istio.io/about/contribute/creating-and-editing-pages/#links-to-github-files)
for context.