Subject: [lisp] Issue Tracking Procedure

From: Sam Hartman <[email-masked]>
Date: Mon, 08 Jun 2009 14:22:08 -0400

The chairs are seeking comments on the following issue tracking
procedure that we'd like to use with the LISP working group.  While
this is a management issue and so we may not need to get a consensus
on it, we definitely do want to seek input.

We plan to use the tools.ietf.org 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
address or an enhancement they would like to see made in on 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 message.  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 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.

---

From: "Joel M. Halpern" <[email-masked]>
Date: Mon, 08 Jun 2009 14:32:28 -0400

Using an issue tracker seems to be a good practice.
I have two concerns:

1) In some WGs that use the issue tracker, there is a tendency for the 
folks who use it day-to-day to assume that everyone knows the issues by 
number.  So there is often less context in the email messages about the 
issue than there would be without the tracker.  This strikes me as a bad 
idea.

2) If at all possible, we should figure out how to cope well without 
requiring the issue number in the subject line.  Aside from sheer 
clutter (I want descriptive subjects, even if we have issue numbers), I 
have found it hard sometimes, as a participant in WGs using the tracker, 
to know what number I am supposed to put on something.  The tools should 
enable us, not put us in a straight-jacket.  Topics drift for good 
reason, and multiple issues are often related.

Yours,
Joel

Sam Hartman wrote:
> _______________________________________________
> lisp mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/lisp
>

---

From: Sam Hartman <[email-masked]>
Date: Mon, 08 Jun 2009 14:48:25 -0400

I forgot to cover a couple of things:

                          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.

--Sam

---

From: David Meyer <[email-masked]>
Date: Mon, 8 Jun 2009 13:25:11 -0700

> chairs will judge the consensus of the working group.

	Seems reasonable. Two issues: 

	(i).	Referring to an issue: Content v. Issue Number

		Frequently there is a non-empty intersection of
		people who don't read the tracker and but who do
		read the mailing list. 

		Sometimes this creates problems if folks refer to
		an issue by number rather than "content" of the
		issue. That can likely be handled by convention,
		or at worst, by reference (to the tracker), but I
		have seen this issue cause confusion.

	(ii).	Creating an issue: DoS attacks

		This hasn't happened here (obviously) but I have
		seen it happen. Do you have an idea of how you're
		going to handle this (other than wait and see what
		happens)? 

		The concern here is malicious use of the tracker
		to impede otherwise legitimate progress that the
		WG may be making.  
		
	Dave

---

From: Sam Hartman <[email-masked]>
Date: Tue, 09 Jun 2009 09:07:43 -0400

>>>>> "David" == David Meyer <[email-masked]> writes:

    David> 	(i). Referring to an issue: Content v. Issue Number

    David> 		Frequently there is a non-empty intersection
    David> of people who don't read the tracker and but who do read
    David> the mailing list.

    David> 		Sometimes this creates problems if folks refer
    David> to an issue by number rather than "content" of the
    David> issue. That can likely be handled by convention, or at
    David> worst, by reference (to the tracker), but I have seen this
    David> issue cause confusion.

Yes.
I'm thinking of something like
Subject [#39] LISP is red not green.

Or in running text "The WG discussed red vs green (#39); the consensus
of the room was that it didn't matter but that for interoperability,
we needed to pick.  Green was chosen."

    David> 	(ii). Creating an issue: DoS attacks

    David> 		This hasn't happened here (obviously) but I
    David> have seen it happen. Do you have an idea of how you're
    David> going to handle this (other than wait and see what
    David> happens)?

    David> 		The concern here is malicious use of the
    David> tracker to impede otherwise legitimate progress that the WG
    David> may be making.

Perhaps my imagination is limited but I cannot think of any new cases
where an issue tracker makes things worse.  This seems to boil down to
how to handle disruptive individuals who are trying to block the WG
process.  The issue tracker helps us keep track of things.  The
obligation to respond to issues that are raised exists independent of
the issue tracker, as do the tools for dealing with disruptions.

The mechanism Eliot suggests doesn't appeal to my style as a chair,
although if things got bad enough I'd adopt something similar.  I'm
certainly committed to making forward progress while the rough
consensus of the WG is to do so.

---

From: Eliot Lear <[email-masked]>
Date: Tue, 09 Jun 2009 16:41:39 +0200

Sam,

> consensus of the WG is to do so.

First, you may not had noticed that I had only addressed my message was 
to the chairs, precisely because I agree with what you say above.  What 
I wrote to the chairs was that if you got into a situation where there 
were some particularly driven individuals on particular points, there 
are mechanisms available to chairs to assist in those situations.  One 
of them is to require a certain number of people to open an issue.  
However, you only do that when you need to, and you only do it at a late 
stage in the process, and not an early stage.  And of course, whether 
you do it at all is at the discretion of the chairs.

Eliot