diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 89f08fde9d..4f8f579493 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,21 +1,30 @@ -> Read our [Contribution guide](https://github.com/eclipse/che-docs/blob/master/CONTRIBUTING.adoc) before submitting a PR. -### What does this PR do? + + -### What issues does this PR fix or reference? +## What does this pull request change? +## What issues does this pull request fix or reference? -### Specify the version of the product this PR applies to. +## Specify the version of the product this pull request applies to +## Pull Request checklist -### PR Checklist +The author and the reviewers validate the content of this pull request with the following checklist, in addition to the [automated tests](code_review_checklist.adoc). -As the author of this Pull Request I made sure that: - -- [ ] `vale` has been run successfully against the PR branch -- [ ] Link checker has been run successfully against the PR branch -- [ ] Documentation describes a scenario that is already covered by QE tests, otherwise an issue has been created and acknowledged by Che QE team -- [ ] Changed article references are updated where they are used (or a redirect has been configured on the docs side): - - [ ] Dashboard [default branding data](https://github.com/eclipse-che/che-dashboard/blob/main/src/services/bootstrap/branding.constant.ts) +- Any procedure: + - [ ] Successfully tested. +- Any page or link rename: + - [ ] The page contains a redirection for the previous URL. + - Propagate the URL change in: + - [ ] Dashboard [default branding data](https://github.com/eclipse-che/che-dashboard/blob/main/packages/dashboard-frontend/src/services/bootstrap/branding.constant.ts) - [ ] Chectl [constants.ts](https://github.com/che-incubator/chectl/blob/master/src/constants.ts) +- [ ] Builds on [Eclipse Che hosted by Red Hat](https://workspaces.openshift.com). +- [ ] the *`Validate language on files added or modified`* step reports no vale warnings. diff --git a/.vale.ini b/.vale.ini index 82e567951f..8d6711c44b 100644 --- a/.vale.ini +++ b/.vale.ini @@ -57,8 +57,13 @@ properties = md BasedOnStyles = CheDocs,IBM,Vale # Ignore code surrounded by backticks or plus sign, parameters defaults, URLs. TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[) +IBM.Annotations = suggestion IBM.HeadingPunctuation = NO IBM.Headings = NO +IBM.Slash = warning +IBM.Usage = suggestion +Vale.Repetition = NO +Vale.Spelling = YES [*.ini] BasedOnStyles = CheDocs,IBM,Vale diff --git a/.vale/styles/Vocab/Che/accept.txt b/.vale/styles/Vocab/Che/accept.txt index 07416b9fa2..43d09166da 100644 --- a/.vale/styles/Vocab/Che/accept.txt +++ b/.vale/styles/Vocab/Che/accept.txt @@ -6,6 +6,8 @@ [Cc]lassloading [Cc]he [Dd]evfile|[Dd]evfiles +[Dd]ownstream +[Dd]ownstreaming [Ff]actories|[Ff]actory [Gg]it [Gg]rafana @@ -22,6 +24,7 @@ [Mm]inikube [Mm]inishift [Mm]ixin|[Mm]ixins +[Mm]odularization [Mm]ulticluster [Mm]ultihost [Mm]ultinode diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 88be08f3b9..267af61628 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -96,7 +96,7 @@ TIP: For Antora, a link:https://docs.antora.org/antora/2.3/module-directories/#m . To review the pull request: -.. Validate the accuracy of content, as well as build, language, links and modular docs requirements. +.. See the xref:code_review_checklist.adoc[code review checklist]. .. For documentation updates containing testable steps, the documentation pull request needs to have the `team/che-qe` label set and get reviewed by both the documentation team and the Che QA team. diff --git a/code_review_checklist.adoc b/code_review_checklist.adoc new file mode 100644 index 0000000000..13ea87ccae --- /dev/null +++ b/code_review_checklist.adoc @@ -0,0 +1,44 @@ +# Pull request review checklist for committers and reviewers +:toc: auto + +The reviewer validates the content of a pull request with this checklist. + +## Automated validation steps + +These automated steps block the pull request merge. + +* [ ] *`Build and validate PR / link checker (pull_request)`* is successful +** [ ] *`Build using Antora`* step is successful: documentation is building without warnings, and all AsciiDoc attributes have a definition. +** [ ] *`Validate links using htmltest`* step is successful: internal and external links are valid. +** [ ] *`Validate language on files added or modified`* step is successful and reports no vale errors: basic language validation, no major deviations from link:https://www.oreilly.com/library/view/the-ibm-style/9780132118989/[IBM Style Guide] and link:https://redhat-documentation.github.io/supplementary-style-guide/[Supplementary Style Guide], and project specific language rules. +* [ ] *`eclipsefdn/eca`* is successful: all contributors have signed the Eclipse Contributor Agreement (ECA). + +## Non automated validation steps + +The author and the reviewers validate the content of a pull request with this additional checklist: + +* Any procedure: +** [ ] Successfully tested. +* Any page or link rename: +** [ ] The page contains a redirection for the previous URL. +** Propagate the URL change in: +*** [ ] Dashboard [default branding data](https://github.com/eclipse-che/che-dashboard/blob/main/src/services/bootstrap/branding.constant.ts) +*** [ ] Chectl [constants.ts](https://github.com/che-incubator/chectl/blob/master/src/constants.ts) +* [ ] Builds on https://workspaces.openshift.com[Eclipse Che hosted by Red Hat]. +* [ ] *`Validate language on files added or modified`* step reports no vale warnings. + +## In depth language review checklist + +The technical writer reviewers validate the language with this additional in depth checklist. We do recognize the subjectivity of some of these objectives. + +- [ ] Content is appropriate for the intended audience. +- [ ] Downstream friendly: correct use of attributes, `ifdef` statements, examples. +- [ ] Effective titles. +- [ ] Follows modularization guidelines. See: link:https://redhat-documentation.github.io/modular-docs/[Modular Documentation Reference Guide]. +- [ ] Follows the principles of minimalism. See: link:https://docs.google.com/presentation/d/1Yeql9FrRBgKU-QlRU-nblPJ9pfZKgoKcU8SW6SQ_UqI/edit#slide=id.g1f4790d380_2_257[The Wisdom of Crowds slides], link:https://youtu.be/s3Em8QSXyn8[The Wisdom of Crowds video], link:https://www.nngroup.com/articles/chunking/[Chunking]. +- [ ] Information is clear, valuable, and concise, no ambiguity. +- [ ] Language is consistent with the rest of the docs. +- [ ] Language is compliant with link:https://www.oreilly.com/library/view/the-ibm-style/9780132118989/[IBM Style Guide] and link:https://redhat-documentation.github.io/supplementary-style-guide/[Supplementary Style Guide] rules not implemented in vale. +- [ ] The information flow is logical. +- [ ] Uses screenshot and other visuals when required. +- [ ] Uses verification steps when necessary.