code_review_checklist.adoc

Pull request review checklist for committers and reviewers

Table of Contents

• Automated validation steps
• Non automated validation steps
• In depth language review checklist

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 IBM Style Guide and 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 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: Modular Documentation Reference Guide.

• ❏ Follows the principles of minimalism. See: The Wisdom of Crowds slides, The Wisdom of Crowds video, Chunking.

• ❏ Information is clear, valuable, and concise, no ambiguity.

• ❏ Language is consistent with the rest of the docs.

• ❏ Language is compliant with IBM Style Guide and 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.