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/main/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.