Context Navigation

Changes between Version 1 and Version 2 of ReviewProcessRevisions

Timestamp:: May 25, 2014, 4:46:56 PM (8 years ago)
Author:: Gordon Woodhull
Comment:: complete first format

Legend:

: Unmodified
: Added
: Removed
: Modified

ReviewProcessRevisions

-              v1
+              v2
 - demystify the process for new library authors
 - encourage more review managers to step forward
+- remove cruft
+In addition, this documents the following new processes:
 - propose the Incubator as a replacement for the queue-which-is-not-a-queue
+- remove cruft
+- the Community Maintenance Team for orphaned libraries
+- mini-reviews for reviewing conditions on acceptance
+- passing on of orphaned reviews
 Except for the new Boost Library Incubator, there is no attempt to improve the process.  The purpose is to document the process as it exists today.
+However, Gordon also includes subjective advice ''in italics'' which could be included or go into an ''Advice for Authors and Review Managers'' page somewhere.
+= Boost Formal Review Schedule page =
+> For context, most of the original text of the pages is quoted
+Subjective advice is ''in italics''; part of the proposal is to include this or put it into an 'Advice for Authors and Review Managers' page.
+= Boost Formal Review Schedule
 http://www.boost.org/community/review_schedule.html
 > Reviews are usually scheduled on a first-come-first-served basis, and normally last ten days. See Formal Review Process for more information.
+> Reviews are usually scheduled --on a first-come-first-served basis, and normally last ten days.-- See Formal Review Process for more information.
 Reviews are scheduled when the review wizards approve a review manager and agree with the manager and author on dates.  Reviews normally last ten days...
 …
 = Boost Library Submission Process page =
+= Boost Library Submission Process
 http://www.boost.org/development/submissions.html
+== Determine interest ==
+> Potential library submitters should use the Boost developers mailing list as a forum to gauge interest a possible submission.
+... use the Boost developers mailing list and Boost Library Incubator as forums to ...
+== Determine interest
+> Potential library submitters should --use the Boost developers mailing list as a forum-- to gauge interest a possible submission.
+... use the Boost developers mailing list and Boost Library Incubator as forums ...
 > A message might be as simple as "Is there any interest in a library which solves Traveling Salesperson problems in linear time?"
 > A bit of further description or snippet of code may be helpful. Messages should be plain text; not rich text, HTML, etc.
 > Please don't post lengthy descriptions, documentation, or code to the mailing list, and no attachments, even small ones.  Please post lengthy material in the YahooGroups boost Files section (formerly called the " vault").
 Please post your code to a version control system such as Github, and make your documentation available in HTML format on a public website.  An issue tracker is also (suggested/required).
+Please post your code to a version control system such as Github, and make your documentation available in HTML format on a public website.  An issue tracker is also highly recommended.
 Release your code under the (Boost Software License).
 (Move from Formal Review section)
 Please verify that your submission compiles and runs under at least two compilers. This flushes out obvious portability problems.
+> Please verify that your submission compiles and runs under at least two compilers. This flushes out obvious portability problems.
 ''While participation in prior reviews is not a prerequisite for submitting a library to Boost, it is highly recommended because it will acquaint you with the process and the emotional demands of a formal review.''
 == Preliminary submission ==
+== Preliminary submission
 > If response to an initial query indicates interest, then make your preliminary submission publicly available if you haven't already done so.
 …
 (Remove this step. Everyone seems to be fine with putting their code in version control from the get-go.)
 == Refinement ==
+== Refinement
 > Discuss, refine, resubmit. Repeat until satisfied.
 > The exact details of this process varies a lot. Sometimes it is public, on the mailing list, sometimes a lot of discussion happens in private emails. For some libraries the process is over quickly, for others it goes on for months.  It's often challenging, and sometimes leads off in completely unexpected directions.
 > The archive of past messages is one way to see how this process worked for other Boost libraries.
 …
 == Submission for review ==
+== Submission for review
 > All of the files which make up the library should be combined and compressed into a single submission file using the .zip format. Free encoders and decoders for this format running on many different platforms are available at the Info-ZIP web site, which includes a FAQ and much other useful information about the .zip format. Many commercial compressor-archiver utilities also support this format.
 …
 (Pure cruft!  Remove section, move directory structure requirement to Formal Review step or Determine Interest step.)
 == Formal Review ==
+== Formal Review
 > Before asking for formal review, your submission should be easilly accessible to all. Please verify that your submission compiles and runs under at least two compilers. This flushes out obvious portability problems. If you don't have access to a second compiler, ask for help on the Boost mailing list.
 …
 === Boost Formal Review Process page ===
+= Boost Formal Review Process page
 http://www.boost.org/community/reviews.html
 == Before Requesting a Formal Review ==
 > Read and follow the Boost submission process. There are at least four steps a library author must take before a formal review is requested.
+== Before Requesting a Formal Review
+> Read and follow the Boost submission process. There are --at least four steps-- a library author must take before a formal review is requested.
 ... several steps ...
 == Introduction ==
+== Introduction
 > Proposed libraries are accepted into Boost only after undergoing a formal review, where Boost mailing list members comment on their evaluation of the library.
 …
 > Private comments to a library submitter may be helpful to her or him, but won't help the Review Manager reach a decision, so the other forms are preferred.
 What to include in Review Comments
 (This still seems up-to-date to me, notwithstanding the common complaint that reviewers make their acceptance conditional on adding more stuff.  But that's out of scope here.)
 Results
 At the conclusion of the comment period, the Review Manager will post a message to the mailing list saying if the library has been accepted or rejected. A rationale is also helpful, but its extent is up to the Review Manager. If there are suggestions, or conditions that must be met before final inclusion, they should be stated.
 Notes for Review Managers
 Before a library can be scheduled for formal review, an active boost member not connected with the library submission must volunteer to be the "Review Manager" for the library.
 The Review Manager:
         * Checks the submission to make sure it really is complete enough to warrant formal review. See the Boost Library Requirements and Guidelines. If necessary, work with the submitter to verify the code compiles and runs correctly on several compilers and platforms.
+(The Incubator automates this somewhat.  The rest of this section LGTM.)
         * Decides if there is consensus to accept the library, and if there are any conditions attached.
+[Advice: Consensus is not the same as a vote.  The Review Manager has discretion to weigh opinions based on authority or thoughtfulness.]
 Notes for Library Submitters
+== What to include in Review Comments
+(This hasn't changed.)
+== Results
+> At the conclusion of the comment period, the Review Manager will post a message to the mailing list saying if the library has been accepted or rejected. A rationale is also helpful, but its extent is up to the Review Manager. If there are suggestions, or conditions that must be met before final inclusion, they should be stated.
+== Notes for Review Managers
+> Before a library can be scheduled for formal review, an active boost member not connected with the library submission must volunteer to be the "Review Manager" for the library.
+> The Review Manager:
+>       * Checks the submission to make sure it really is complete enough to warrant formal review. --See the Boost Library Requirements and Guidelines--. If necessary, work with the submitter to verify the code compiles and runs correctly on several compilers and platforms.
+See the Boost Library Requirements and Guidelines - or submitting through the Boost Library Incubator will
+>       * Decides if there is consensus to accept the library, and if there are any conditions attached.
+''Consensus is not the same as a vote.  The Review Manager has discretion to weigh opinions based on authority or thoughtfulness.''
+== Notes for Library Submitters
 (Unchanged.)
 Library Maintainer's Rights and Responsibilities
 By submitting a library to boost, you accept responsibility for maintaining your library or finding a qualified volunteer to serve as maintainer. You must be willing to put your library and documentation under a Boost-compatible license.
 You will be expected to respond to reasonable bug reports and questions in a timely manner and to participate as needed in discussions of your library on the boost mailing lists.
 You are free to change your library in any way you wish, and you are encouraged to actively make improvements. However, peer review is an important part of the Boost process and as such you are also encouraged to get feedback from the boost community before making substantial changes to the interface of an accepted library.
 If at some point you no longer wish to serve as maintainer of your library, it is your responsibility to make this known to the boost community and to find another individual to take your place.
+== Library Maintainer's Rights and Responsibilities
+> By submitting a library to boost, you accept responsibility for maintaining your library or finding a qualified volunteer to serve as maintainer. You must be willing to put your library and documentation under a Boost-compatible license.
+> You will be expected to respond to reasonable bug reports and questions in a timely manner and to participate as needed in discussions of your library on the boost mailing lists.
+> You are free to change your library in any way you wish, and you are encouraged to actively make improvements. However, peer review is an important part of the Boost process and as such you are also encouraged to get feedback from the boost community before making substantial changes to the interface of an accepted library.
+> If at some point you no longer wish to serve as maintainer of your library, it is your responsibility to make this known to the boost community and to find another individual to take your place.
 Libraries which have been abandoned will be put in care of the Community Maintenance Team.
 Review Wizard
+== Review Wizard
 (Responsibilities have changed considerably here.)
 The Review Wizard coordinates the formal review schedule:
+> The Review Wizard coordinates the formal review schedule:
 (Ok)
         * Maintains a list of review manager volunteers, in the form of a queue, so that volunteers who least recently managed reviews become the prime candidates for upcoming reviews.
+>       * Maintains a list of review manager volunteers, in the form of a queue, so that volunteers who least recently managed reviews become the prime candidates for upcoming reviews.
 (Nix.  There is no manager volunteer queue, because domain knowledge and interest are required.)
+        * When a formal review is requested for a library:
+                * Assign a review manager and
+* Approve the review manager based on their participation in the Boost community, including the mailing list.
+[and previous reviews?  Stack Overflow participation?]
+>       * When a formal review is requested for a library:
+>               * --Assign a review manager-- and
+* Approve the review manager based on their participation in the Boost community, including the mailing list.  ''and previous reviews?  Stack Overflow participation?''
 * Suggest a schedule, after checking (via private email) availability of the volunteers
                 * Finalize the schedule, once the review manager verifies the library is actually ready for review.
                 * Resolve schedule slips or other issues with review managers and submitters.
+>               * Finalize the schedule, once the review manager verifies the library is actually ready for review.
+>               * Resolve schedule slips or other issues with review managers and submitters.
 (Ok)
 (Bikeshed question: do we continue to call it a review queue, but say "the queue is not a queue"?  Also consider replacing the queue with the Incubator.)
         * Maintains a schedule of both past and pending reviews, in the form of the Review Schedule web page.
         * Resolves questions from review managers and library submitters, who sometimes want a third opinion on questions such as "Should we extend the review period because ...?"
         * Monitors the general review process, and makes minor adjustments as needed, or queries the list about possible major adjustments.
 The role of Boost Review Wizard is currently played by John Phillips (johnphillipsithaca at gmail dot com) and Ronald Garcia (rxg at cs dot ubc dot ca).
+(Bikeshed question: do we continue to call it a review queue, but say "the queue is not a queue"?  Or simply replace the Queue with the Incubator?)
+>       * Maintains a schedule of both past and pending reviews, in the form of the Review Schedule web page.
+>       * Resolves questions from review managers and library submitters, who sometimes want a third opinion on questions such as "Should we extend the review period because ...?"
+>       * Monitors the general review process, and makes minor adjustments as needed, or queries the list about possible major adjustments.
+> The role of Boost Review Wizard is currently played by John Phillips (johnphillipsithaca at gmail dot com) and Ronald Garcia (rxg at cs dot ubc dot ca).
 (Still current.)
+Fast Track Reviews
+To qualify for fast track review:
+        * The component must be small.
+        * The technique must be already in use in Boost libraries and the new component provides a common implementation.
+        * A full Boost-conformant implementation is available in the sandbox.
+        * The Review Wizard determines that the proposal qualifies for fast track review.
+Procedure:
+        * The Boost Review Wizard posts a review announcement to the main Boost developer's list. The review period will normally last for 5 days. No two fast track reviews will run in parallel. Fast track reviews may run during full reviews, though generally this is to be avoided.
+        * After the review period ends, the submitter will post a review summary containing proposed changes to the reviewed implementation.
+        * The Review Wizard will accept or reject the proposed library and proposed changes.
+        * After applying the proposed changes, the component is checked into the repository like any other library.
+= Fast Track Reviews
+> To qualify for fast track review:
+>       * The component must be small.
+>       * The technique must be already in use in Boost libraries and the new component provides a common implementation.
+>       * A full Boost-conformant implementation is available in the sandbox.
+>       * The Review Wizard determines that the proposal qualifies for fast track review.
+> Procedure:
+>       * The Boost Review Wizard posts a review announcement to the main Boost developer's list. The review period will normally last for 5 days. No two fast track reviews will run in parallel. Fast track reviews may run during full reviews, though generally this is to be avoided.
+>       * After the review period ends, the submitter will post a review summary containing proposed changes to the reviewed implementation.
+>       * The Review Wizard will accept or reject the proposed library and proposed changes.
+>       * After applying the proposed changes, the component is checked into the repository like any other library.
+== Mini-Reviews ==
 (add section)
-Mini-Reviews
 If a review results in conditions on acceptance, the review manager may request a Mini-Review to determine if the conditions have been met.  The Mini-Review is usually conducted by the same review manager.
+(possibly add section)
+[Abandoned Reviews
 If a review manager has not delivered a report in a reasonable time after the review, another member of the community may volunteer to manage the review retroactively.  The volunteer must seek approval of the previous review manager, author, and review wizards off-list.  The replacement manager will write the report based on the review discussion and submit the report to the original review manager for sign-off.]
+== Orphaned Reviews ==
+(add section)
+If a review manager has not delivered a report in a reasonable time after the review, another member of the community may volunteer to manage the review retrospectively.  The volunteer must seek approval of the previous review manager, author, and review wizards off-list.  The replacement manager will write the report based on the review discussion and submit the report to the original review manager for sign-off.