LISP Issue Tracking Policy

We use the issue tracker to track open issues with the LISP specifications to make sure that they are addressed. However, discussion will take place on the mailing list. The issue tracker represents summaries of the issues and their resolution; new content needs to appear on the list.

The issue tracker will be managed by document editors, the WG secretary and the WG chairs. These people will be responsible for creating, updating and resolving issues based on the WG discussion. Especially for creating issues, we hope that the document editors will take the initiative.

Creating an Issue

Whenever a WG participant flags a problem they believe needs to be addressed or an enhancement they would like to see made in one of our documents in a message, the document editors should open a new issue and reply to the message including the issue number in the subject.

WG participants should try to include only one issue per message when opening a issue. However when opening issues in the tracker, it may be necessary to split a message into multiple issues. It may be tricky to figure out where the boundary between issues is. It's probably reasonable to include several editorial recommendations in an issue. It may be reasonable to include several text changes to different sections that together effect one consistent technical change as a single issue. However it is desirable to separate technical issues where the WG may have different opinions. It is better to err on the side of separating rather than combining issues.

Commenting on Issues

It is important that whenever possible a reply to an issue include the issue number in the subject and only address one issue per message. WG participants are strongly encouraged to wait for an issue to be opened and assigned a number before replying to a message opening an issue.

Closing Issues

If the document editor replies to an issue, and the person opening the issue agrees then the issue can be closed. There need not be text changes; some times discussion reveals that the text is clear or that the desired change is not a good idea. If an issue is closed with no text change, it should be closed as resolved/withdrawn. If an issue is closed with text changes resolving the issue it should be closed as resolved/fixed. If someone objects to the issue being closed within a reasonable time then it will be reopened.

If agreement is not reached between the document editor and person opening the issue or if objections are raised by others, then the WG chairs will judge the consensus of the working group. In this case document editors must wait for the results of the consensus call before making text changes to address the issue.

Whenever an issue is marked fixed, a description of the text changes to address that issue need to be attached to the issue.

Content of Issues

The issue tracker should contain a description of the issue, a summary of the discussion and the resolution of the issue. If specific text changes are made in response to an issue they need to be included. Quoting messages to the list to provide the description of the issue and the summary of discussion is encouraged. However it is not important to quote all traffic on the list unless doing so adds clarity.

Changes Summaries

When Document editors post new versions of their drafts, they should briefly describe the changes in the draft and their motivation. An example might be something like "Changed LISP header (issue 32)". Editorial changes do not need to be explicitly called out. Not all changes need to be linked back to the issue tracker, although more explanation for the change is needed if an issue is not referenced so the WG can tell why the change was made and the level of discussion/consensus.

Last modified 13 years ago Last modified on 11/08/09 19:51:01