Skip to content

Latest commit

 

History

History
44 lines (34 loc) · 3.02 KB

code_review_checklist.adoc

File metadata and controls

44 lines (34 loc) · 3.02 KB

Pull request review checklist for committers and reviewers

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:

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.