https://github.com/mnot/ietf-comments
Automating IETF comment handling
https://github.com/mnot/ietf-comments
github ietf markdown python
Last synced: 4 months ago
JSON representation
Automating IETF comment handling
- Host: GitHub
- URL: https://github.com/mnot/ietf-comments
- Owner: mnot
- License: bsd-2-clause
- Created: 2022-03-06T08:37:17.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-02-04T00:03:48.000Z (12 months ago)
- Last Synced: 2025-09-22T17:24:56.219Z (4 months ago)
- Topics: github, ietf, markdown, python
- Language: Python
- Homepage:
- Size: 150 MB
- Stars: 4
- Watchers: 3
- Forks: 4
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# The IETF Comments Processor
Handling comments from the IESG, multiple directorate reviews, and in AUTH48 can be burdensome for document authors, because of the sheer number of comments, and because they come in an unstructured format that has to be manually processed.
This package installs two commands:
* `ietf-comments` processes comments from the IESG and directorates in a [markdown](https://commonmark.org)-based format.
* `rfced-comments` processes comments from the RFC Editor in RFC XML files.
Both can be used to create GitHub issues for the comments they find. When used properly, they can help automate formerly tiresome tasks.
For IESG and directorate comments, this tool uses the [IETF Comment Markdown format](https://github.com/mnot/ietf-comments/tree/main/format.md), which is a semi-structured format that is similar to that which ADs and directorates use now. Ideally, they will create comments in that format for easy processing, but even when they don't, most comments can easily be transformed into it for processing.
## Online Validator
If you just need to validate markdown comments, see the [online comments validator](https://mnot.github.io/ietf-comments/).
## Installation
To install ietf-comments, you'll need [Python](https://www.python.org/).
The best way to install it is using [pipx](https://pypa.github.io/pipx/), because that will automatically create an isolated environment for the dependencies:
> pipx install ietf-comments
**Note** that to use rfced-comments, you'll need Python 3.10 or greater. To assure that Python 3.10 is being used, you may need to use something like:
> pipx install ietf-comments --python /path/to/python3.10
## Use
### Processing AD and Directorate Comments
To validate a AD or Directorate review in the [IETF Comment Markdown format](https://github.com/mnot/ietf-comments/tree/main/format.md) and see the identified issues, run:
> ietf-comments _filename_
To create a GitHub issue for each issue, set `GITHUB_ACCESS_TOKEN` in your environment to a [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and run:
> ietf-comments -g _owner/repo_ _filename_
... where `owner/repo` is the repo owner and name, separated by a slash.
If you'd like these issues to have a specific label, run:
> ietf-comments -g _owner/repo_ _filename_ -l _labelname_
If you'd like `discuss`, `comment`, and `nit labels` added as appropriate, along with a `review` label, pass `-a`:
> ietf-comments -g _owner/repo_ _filename_ -a
### Processing RFC Editor Comments
To validate RFC Editor comments in a local RFC XML file and see the identified issues, run:
> rfced-comments _filename_
Alternatively, if you're in AUTH48 and the RFC Editor has published a draft of your RFC-to-be, you can just run
> rfced-comments _NNNN_
where `NNNN` is the RFC number.
To create a GitHub issue for each issue, set `GITHUB_ACCESS_TOKEN` in your environment to a [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and run:
> rfced-comments -g _owner/repo_ _NNNN_or_filename_
... where `owner/repo` is the repo owner and name, separated by a slash.
If you'd like these issues to have a specific label, run:
> rfced-comments -g _owner/repo_ _NNNN_or_filename_ -l _labelname_
## Special Features
The following features are currently supported (more soon!):
* When recognised, internal section references (e.g., `Section 2.4`) are auto-linked in created issues.
* Likewise, references to external RFCs (e.g., `Section 5.3 of [RFC1234]`) will also be auto-linked in created issues when recognised.
* Text in blockquotes (preceded by `>`) in comments will be checked for presence in the document; if they aren't found, a warning will be raised.