|
|
| (25 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| − | === Goal ===
| + | Read the new content in the [http://docs.openstack.org/contributor-guide/docs-review.html Documentation Contributor Guide]. |
| | | | |
| − | Provide guidelines to improve the quality and speed of the documentation review process.
| + | {{OpenStack_Documentation_Navbar}} |
| − | | |
| − | === Critique Categories ===
| |
| − | | |
| − | ==== Objective ====
| |
| − | | |
| − | # Commit message
| |
| − | ## Content
| |
| − | ## Conventions
| |
| − | ### Tags
| |
| − | # Patch
| |
| − | ## Content
| |
| − | ## Conventions
| |
| − | ## Grammar
| |
| − | ## Style/Phrasing/Wording
| |
| − | ## Spelling
| |
| − | | |
| − | ==== Subjective ====
| |
| − | | |
| − | # Commit message
| |
| − | ## Grammar
| |
| − | ## Spelling
| |
| − | ## Style/Phrasing/Wording
| |
| − | # Patch
| |
| − | ## Grammar
| |
| − | ## Style/Phrasing/Wording
| |
| − | ## Other suggestions
| |
| − | | |
| − | === Scope ===
| |
| − | | |
| − | # Try to keep reviews limited to the contents of the bug, contents of the commit message, and changes made by the patch.
| |
| − | | |
| − | === Consistency ===
| |
| − | | |
| − | # If you find an issue, do your best to mark all instances of it.
| |
| − | ## If the author uploads a patch correcting your objective issue and you find another instance that you didn't mark, comment on it and score with a -1. Preferably, upload a patch to fix it.
| |
| − | ## If the author uploads a patch correcting your subjective issue and you find another instance that you didn't mark, comment on it and score with a 0.
| |
| − | ## If the author uploads a patch correcting your objective and/or subjective issue and you find another objective issue, comment on it and score with a -1. Preferably, upload a patch to fix it.
| |
| − | ## If the author uploads a patch correcting your objective and/or subjective issue and you find another subjective issue, comment on it and score with a 0.
| |
| − | # If you find an issue that could affect other portions of a book, provide appropriate comments, score the patch with a -1, and consider mentioning your issue on the mailing list or in a meeting.
| |
| − | ## Example: A new service uses "key = value" in the configuration file and all other services use "key=value" in their configuration files. Both methods work, but the book should maintain consistency.
| |
| − | | |
| − | === Tagging Additional Reviewers ===
| |
| − | | |
| − | # In some cases, you should tag one or more people with interest in or experience with the content of your patch to review it.
| |
| − | ## How long should an author wait for reviews by these people?
| |
| − | | |
| − | === The Waiting Game ===
| |
| − | | |
| − | # After the first review with a 0 or -1 score, how long should an author wait for additional reviews before addressing issues in the first review?
| |
| − | | |
| − | === Review Scoring and Approvals ===
| |
| − | | |
| − | # Scores available to contributors
| |
| − | ## -1, 0, +1
| |
| − | # Scores available to core reviewers
| |
| − | ## -2, -1, 0, +1, +2
| |
| − | # Approvals
| |
| − | ## A core reviewer can approve a patch with +4 points, typically after it obtains two +2 scores from other core reviewers.
| |
| − | ## A core reviewer can +2 score a patch with a +2 score from another core reviewer and approve it.
| |
| − | | |
| − | Note: If you find an issue with a patch that already has a +2 score from another core reviewer, consider commenting on the issue and scoring the patch with a 0 rather than scoring it with a -1.
| |
| − | | |
| − | === Considerations for Documentation Aligned with Release Cycles ===
| |
| − | | |
| − | # Beginning with milestone releases, shift focus to objective issues, especially with new services and existing services with significant changes. Only patches with significant subjective issues should receive a -1 score. Otherwise, comment on subjective issues and score with a 0.
| |
| − | # Beginning with release candidates, focus almost entirely on content issues. Only comment on subjective issues if the patch should receive a -1 score for objective issues.
| |
