The IETF Comments Markdown Format
The IETF Comment Markdown Format is a markdown dialect for describing IETF review comments. Following common practice, it uses h2 headings to identify three main levels of comments (or issues):
- Discuss - a significant issue that requires further discussion
- Comment - an issue that was noticed, but is not significant enough to block document progress
- Nit - a minor (usually, editorial) issue that the reviewer noticed; no response is necessary, but the author might want to take it into consideration.
See the examples directory for examples of the format in use.
This page summarises the format for reviewers. Reviewers can validate a document using the command-line tool; e.g.,
> ./ietf-comments _filename_Document Header
The document should start with a header indicating the title of the review; for example:
# Security AD comments for draft-ietf-whatever-document-08It must:
- Be a
h1header (i.e., one octothorp) - Be the only
h1header in the document - Identify the reviewer, either by name or position
- Identify the draft being reviewed by its with revision number
Optionally, a reviewer can indicate that they want their GitHub username to be @ mentioned in any issues created by adding a line after the h1 header that starts with CC, followed by their GitHub username; for example:
CC @mnotThis first part can contain other content (e.g., acknowledgements, a preface, etc.) that will not be converted into issues.
Review Comments
Then, the document can contain discuss, comment, and nit positions, each in their own subsection indicated by a h2 header. Issues within a section should each have a descriptive title in a h3 header (i.e., two octothorps); if there are no h3 headers, the entire section will be considered a single issue.
Comments can contain any markdown, including blockquotes, links, emphasis, lists, etc.
For example:
## Discuss
This document has serious implications for the space/time continuum. We should discuss.
## Comments
### Wrong references
The references in section 2.1 are not correct.
### Does it work that way?
The widget in s 5.4.3 doesn't seem well-specified; are you sure?
### I don't like it.
The whole thing. But I won't make it a discuss.
## Nits
### Missing pages
The following pages are missing:
* 53
* 49
* 42