IEEE Comment Resolution

The comment resolution process

When balloting an IEEE standard, in one or more circulations, members submit comments and a determined comment resolution group resolves these comments until a certain approval rate is met. The details of the process are described here.

Effectively, comments can be downloaded as XLSX and bulk edited by filling in the columns Disposition Status and Disposition Detail. In each circulation, a dedicated XLSX is generated, processed and uploaded back to IEEE servers.

As documents and issues are collected in OR.NET GitHub repositories, and officially published comments are otherwise opaque to the authoring members, the IEEE GitHub comment resolution tool helps

• transferring IEEE balloting comments from XLSX to GitHub and
• disposition statuses and details back from GitHub to XLSX.

This page gives instructions as to how the comment resolution tool can be used and which GitHub issue style to adhere to in order to read disposition information.

The following diagram roughly depicts the comment resolution using the comment resolution tool and Github:

---
config:
theme: redox
---
stateDiagram-v2
    GitHub: GitHub issues
    GitHub --> Read
    Read --> [*]
    
    Write: --write-comments
    Read: --read-dispositions
    [*] --> Write: XLSX with at least one comment is available
    Write --> GitHub

    state GitHub {
        Assign: Assign issue
        Work: Work on issue
        SetLabel: Assign disposition status label
        WriteDetail: Write disposition detail
        Close: Close issue
        
        [*] --> Assign: Open issues available
        Assign --> Work
        Work --> SetLabel
        SetLabel --> WriteDetail: rejected, revised
        SetLabel --> Close: accepted
        WriteDetail --> Close
        Close --> Assign: Open issues available
        Close --> [*]: All issues closed
    }

Loading

Description of states

• --write-comments: initially, comments are added to GitHub as issues, see Transferring comments to GitHub.
• Assign issue: assigning an open issue in GitHub initiates the resolution process.
• Work on issue: work is done in accordance with the GitHub editing process.
• Assign disposition status label: once the work is done, the assignee has to add a disposition status label to the issue, one of rejected, revised, or accepted, see also Use of labels.
• Write disposition detail: in case of rejected or revised, the assignee also has to provide disposition detail.
• Close issue: once the issue is labeled and, optionally, disposition detail exists, the issue needs to be closed in order to be detected by the comment resolution tool.
• --read-dispositions: when all issues of the ballot round are closed, disposition information can be written back to the XLSX document, see Transferring disposition information from GitHub.

The comment resolution process tool

To batch-write IEEE comments to GitHub and back to XLSX, you need to run the IEEE GitHub comment resolution tool. Instructions for use can be found here.

Download a copy of the latest distribution and configure it accordingly. You need to create a GitHub token to access the GitHub API through the comment resolution tool.

Warning

Treat your access tokens like passwords!

Example config:

showStacktraceOnError = false

[github]
token = "ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
repository = "standard-development-process"
milestone = "ieee-11073-107xx-2025"
labels = ["initial-ballot"]

[commentWriter]
xlsxInputFile = "ieee-11073-107xx-2025-InitialBallot_comments.XLSX"
startAt = 0
dryRun = true

[dispositionReader]
xlsxInputFile = "ieee-11073-107xx-2025-InitialBallot_comments.XLSX"
xlsxOutputFile = "ieee-11073-107xx-2025-InitialBallot_comments_resolved.XLSX"

Description of properties

• showStacktraceOnError: set to true to increase error output verbosity.

Section github:

• token: the GitHub token to be used to request GitHub.
• repository: the repository name in the OR.NET GitHub space.
• milestone: a milestone to filter against, see Use of milestones.
• labels: one or more labels to filter against, see Use of labels.

Milestones and labels are important to reduce the amount of data that is exchanged between GitHub and the comment resolution tool.

Section commentWriter:

• xlsxInputFile: path to the input file used by the comment writer.
• startAt: whenever there is an error at a specific index, the error cause may be fixed and the writing process to be continued at startAt (rather than removing all successfully written items from GitHub beforehand).
• dryRun: to avoid ugly surprises during the writing process, e.g., because there is something misformatted in the input file, a dry run helps identify problems before something is actually pushed to GitHub. Set to true to execute a dry run, false otherwise.

Section dispositionReader:

• xlsxInputFile: the XLSX input file (will not be overwritten).
• xlsxOutputFile: the XLSX output file, which is a copy of the input file supplemented by disposition information.

Naming conventions

The GitHub issue tracker of the standard development repository should follow the following milestone and label pattern.

Use of milestones

For each revision of a standard document, a new milestone should exist. The name of the milestone depends on if the document is going to be a revision, amendment or corrigendum.

Base name

ieee-<standard_number>

where standard_number identifies the initial standard version, e.g.:

ieee-11073-10207

for the initial BICEPS standard.

Revision name

<base_name>-<release_year>-rev

where

• base_name describes the base name, and
• release_year pertains to the year of the standard that is being revised.

Example: ieee-11073-10207-2017-rev for the revision of the BICEPS standard published in 2017.

Amendment name

<base_name>-<release_year>-amend-<amendment_number>

where

• base_name describes the base name,
• release_year pertains to the year of the standard that is being amended, and
• amendment_number is the consecutive amendment number.

Example: ieee-11073-10207-2017-amend-1 for the first amendment of the BICEPS standard published in 2017.

Corrigendum name

<base_name>-<release_year>-cor-<corrigendum_number>

where

• base_name describes the base name,
• release_year pertains to the year of the standard that is being amended, and
• corrigendum_number is the consecutive corrigendum number.

Example: ieee-11073-10207-2017-cor-2 for the second corrigendum of the BICEPS standard published in 2017.

Use of labels

Labels are generally free to choose with the following exceptions:

• accepted expressing the disposition status ACCEPTED
• rejected expressing the disposition status REJECTED
• revised expressing the disposition status REVISED
• initial: expressing a comment belonging to an initial ballot circulation
• recirc-<recirc_number>: expressing a comment belonging to the recirc_number^th ballot recirculation.

Writing disposition detail

Disposition detail is added to a GitHub issue by adding a comment that contains a heading level 2 section of the following format:

## Disposition Detail

<your_text_here>

Important

The heading title needs to be exactly Disposition Detail as otherwise the tool will not recognize it appropriately.

The text of that paragraph is transferred to the Disposition Detail column of the XLSX file.

Caution

Disposition detail should not contain Markdown markup, since the XLSX file cannot digest any such data.

Note

You may add further sections to the GitHub comment, only the first heading level 2 named Disposition Detail will be recognized.

Transferring comments to GitHub

Assuming that the config file named app-config.toml resides in the same directory as the comment resolution tool named ieee-github-comment-resolution.jar, the following command performs the writing process to GitHub:

java -jar ieee-github-comment-resolution.jar --write-comments

Transferring disposition information from GitHub

Assuming that the config file named app-config.toml resides in the same directory as the comment resolution tool named ieee-github-comment-resolution.jar, the following command performs the writing process to XLSX:

java -jar ieee-github-comment-resolution.jar --read-dispositions

Caution

In order for the disposition information to be recognized by the comment resolution tool, corresponding GitHub issues need to be closed.