Changes between Version 1 and Version 2 of WikiStart

May 20, 2010, 1:39:07 PM (10 years ago)

Populating wiki with GEN-ART guidelines from


  • WikiStart

    v1 v2  
    1 = Welcome to Trac 0.10.3 =
     1= General Area =
    3 Trac is a '''minimalistic''' approach to '''web-based''' management of
    4 '''software projects'''. Its goal is to simplify effective tracking and handling of software issues, enhancements and overall progress.
     3== General Area Review Team (GEN-ART) Guidelines ==
    6 All aspects of Trac have been designed with the single goal to
    7 '''help developers write great software''' while '''staying out of the way'''
    8 and imposing as little as possible on a team's established process and
    9 culture.
     5These are guidelines for document review within the GEN-ART.
    11 As all Wiki pages, this page is editable, this means that you can
    12 modify the contents of this page simply by using your
    13 web-browser. Simply click on the "Edit this page" link at the bottom
    14 of the page. WikiFormatting will give you a detailed description of
    15 available Wiki formatting commands.
     7See also: FAQ, Reviewer list, [ Summary of Reviews]
    17 "[wiki:TracAdmin trac-admin] ''yourenvdir'' initenv" created
    18 a new Trac environment, containing a default set of wiki pages and some sample
    19 data. This newly created environment also contains
    20 [wiki:TracGuide documentation] to help you get started with your project.
     9=== Timeline of Review ===
    22 You can use [wiki:TracAdmin trac-admin] to configure
    23 [ Trac] to better fit your project, especially in
    24 regard to ''components'', ''versions'' and ''milestones''.
     11Documents are typically assigned to a GEN-ART reviewer during IETF-LC.  The
     12documents may be re-reviewed once they appear on a Telechat agenda. 
     13Documents may also be reviewed at the request of ADs prior to IETF-LC.
     15The process for reviewing Early documents:
    27 TracGuide is a good place to start.
     17* The Secretary assigns a reviewer when a request comes in from an AD via the IETF chair. The assignments are typically done on Thursday evenings, along with any LC assignments.
     18* We expect the reviewer to be done before the deadline (typically 2 weeks).
     19* The reviewer sends the review to the Gen-ART list
     20* The reviewer also sends the review to the AD, WG chairs & authors, and optionally to the WG mailing list.
    29 Enjoy! [[BR]]
    30 ''The Trac Team''
     22The process for reviewing documents at Last Call:
    32 == Starting Points ==
     24* The Secretary assigns a reviewer, more or less randomly using a round robin order,  within a week of the Last Call announcement – typically on Thursday evenings.
     25* We expect the reviewer to be done before the end of Last Call.
     26* The reviewer sends the review to the Gen-ART list
     27*  The reviewer also sends the review to the AD, WG chairs & authors, and optionally to the WG mailing list.  Since IETF Last Call comments are commonly sent to the IETF discussion list, the reviewer may also choose to do that; in any case the review will be public.
    34  * TracGuide --  Built-in Documentation
    35  * [ The Trac project] -- Trac Open Source Project
    36  * [ Trac FAQ] -- Frequently Asked Questions
    37  * TracSupport --  Trac Support
     29The process for reviewing documents when they appear on the IESG agenda:
    39 For a complete list of local wiki pages, see TitleIndex.
     31* Secretary checks the IESG agenda one week before the IESG telechat. The agenda is typically finalized Thursday evening PDT, with late agenda items sometimes being added on Friday morning, thus the assignments are out either late Thursday evening or early Friday morning (PDT).
     32* For documents reviewed at Last Call, a new review is only asked for if the document is revised or issues resolved.
     33* The Secretary names a reviewer per document, more or less randomly. For documents that have been reviewed before, the same reviewer is kept, if that person is still available.
     34* Reviewers send their review to the Gen-ART list no later than COB  (i.e., 8 PM CDT) the Tuesday before the telechat (earlier is better!)
     35*  Reviews should be copied to authors, responsible ADs and WG chairs, unless the review finds no issues. Also, including a link to the FAQ in the email has proved essential for the recipients of the review in understanding the context.
     36* If the AD concludes that the concerns raised by the reviewer warrant blocking the document, the AD will do so.
     38The following aliases can be helpful in getting the reviews to the right targets, replacing  draftname by !draft-ietf-wg-topic  (without -xx version)
     40|| !     || Draft authors (for now, could change)
     41|| ! || Draft authors
     42|| ! || WG Chairs (if the draft is a WG draft)
     43|| ! || The addresses entered into the tracker's  email notification field for the draft
     44|| ! || The sponsoring AD, if the draft has gone to the IESG
     45|| ! || All of the above, merged into one alias
     47The telechats are every other Thursday, with the [ agenda] published on the Thursday evening one week prior to the telechat.
     49=== Form of review ===
     51Each review must include one of the following at the beginning of the review:
     53* For Early reviews:
     54I am the assigned Gen-ART reviewer for draft-FOOBAR.txt.
     56For background on Gen-ART, please see the FAQ at <>.
     58Please resolve these comments along with any other comments you may receive.
     60* For IETF Last Call reviews:
     61I am the assigned Gen-ART reviewer for draft-FOOBAR.txt.
     63For background on Gen-ART, please see the FAQ at <>
     65Please resolve these comments along with any other comments you may receive.
     67* For IESG Evaluation reviews:
     68I am the assigned Gen-ART reviewer for draft-FOOBAR.txt.
     70For background on Gen-ART, please see the FAQ at <>
     72Please wait for direction from your document shepherd or AD before posting a new version of the draft.
     74Each review must include a summary statement chosen from or adapted from the following list:
     76* This draft is ready for publication as a [type] RFC, where [type] is Informational, Experimental, etc. (In some cases, the review might recommend publication as a different [type] than requested by the author.)
     77* This draft is basically ready for publication, but has nits that should be fixed before publication.
     78* This draft is on the right track but has open issues, described in the review.
     79* This draft has serious issues, described in the review, and needs to be rethought.
     80* This draft has very fundamental issues, described in the review, and further work is not recommended.
     81* Unfortunately, I don't have the expertise to review this draft.
     83The length of a review will vary greatly according to circumstances, and it is acceptable for purely editorial comments to be sent privately if it's obvious that the document will have to be substantially revised anyway. All substantive comments must be included in the public review. Wherever possible, they should be written as suggestions for improvement rather than as simple criticism. Explicit references to prior work and prior IETF discussion should be given.
     85Reviewers should review for all kinds of problems, from basic architectural or security issues, Internet-wide impact, technical nits, problems of form and format (such as IANA Considerations or incorrect references),and editorial issues. Since these reviews are on documents that are supposed to be finished, the review should consider "no issue too small" - but cover the whole range from the general architectural level to the editorial level. However, a review which consists only of copy-editing is not productive. If the reviewer feels that a draft is too badly written to advance, it will be sufficient to say so with one or two examples.
     87The review should apply generally agreed IETF criteria, such as
     89[RFC1958] The Architectural Principles of the Internet
     90[RFC3426] General Architectural and Policy Considerations
     91[RFC3439] Some Internet Architectural Guidelines and Philosophy
     92[NITS] The "I-D Nits" document maintained by the IESG
     93[RFC2223] Instructions to RFC Authors
     94[BCP26] Guidelines for Writing an IANA Considerations Section in RFCs
     95[RFC3552] Guidelines for Writing RFC Text on Security Considerations
     97as well as any other applicable architectural or procedural documents. It is important that reviews give precise references to such criteria when relevant.
     99Of special interest to the GEN area (because it's no area's special interest) is:
     100* Clear description of why the document or protocol is useful to the Internet
     101* Adherence to IETF formalities such as capitalized MUST/SHOULD (ID-Nits)
     102* Useful and reasonable IANA considerations
     103* Correct dependencies for normative references
     104* That it's written in reasonably clear English
     106Mailing List:   All reviews are posted on the IETF gen-art mailing list:
     108Archiving of reviews:   All reviews are also archived and publicly visible: