Subject: Issue tracking

From: Thomas Narten <[email-masked]>
Date: Tue, 10 Aug 2004 15:54:06 -0400

Folks,

I was just asked to clear my discuss on a document and was pointed to

   http://www.arkko.com/publications/send/issues/

for details of the resolutions.

I must say, this is a really, really nice way of tracking issues, one
of the best I have seen so far. Each isssue is tracked individually
and one can easily see the followup discussion and (very important!)
what text changed to resolve the issue.

What is really nice about this page is that the information is
organized in a way that makes it really easy for an end user to review
the history and how an issue was resolved!

Thank you!!!

Thomas

---

From: David Meyer <[email-masked]>
Date: Tue, 10 Aug 2004 14:07:08 -0700

>> the history and how an issue was resolved!

	This is truly awesome. Makes me feel like I'm not
	tracking drafts in my WGs :-)

	Dave

---

From: Matthew J Zekauskas <[email-masked]>
Date: Tue, 10 Aug 2004 17:31:22 -0400

it is quite nice... but I wonder how much of it was done by hand
(at least the initial page, and maybe the .txt of each issue...)

--Matt

---

From: "bill" <[email-masked]>
Date: Tue, 10 Aug 2004 14:52:28 -0700

Well - can the owners of this page fess up to how much is manual...

And can the tools team look at deploying this a little wider ?

Bill

> -----Original Message-----
> From: [email-masked] 
> [mailto:[email-masked]] On Behalf Of Matthew J Zekauskas
> Sent: Tuesday, August 10, 2004 2:31 PM
> To: [email-masked]
> Subject: Re: Issue tracking
> 
> 
> it is quite nice... but I wonder how much of it was done by 
> hand (at least the initial page, and maybe the .txt of each issue...)
> 
> --Matt
>

---

From: Aaron Falk <[email-masked]>
Date: Tue, 10 Aug 2004 14:52:58 -0700

Seems pretty straightforward to me to save the issue email (or write a 
summary) as 'issueXX.txt' then run htmlwdiff on the resulting changes. 
Then add a line of html.  Probably about the same work as maintaining 
RT but with a very nice presentation.

--aaron

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 11 Aug 2004 00:09:15 +0200

> the history and how an issue was resolved!

Very nice indeed. It seems to me the biggest challenge here, which
cannot be fully automated, is for the editor to resolve only one issue
per sub-version of the draft, and generate an accompanying diff based
on that resolution.

Gotta ponder what kind of tool support could be made for this.

	Henrik

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 11 Aug 2004 00:10:49 +0200

> And can the tools team look at deploying this a little wider ?

Already pondering... :-)

	Henrik

---

From: Jari Arkko <[email-masked]>
Date: Wed, 11 Aug 2004 02:16:22 +0300

> Well - can the owners of this page fess up to how much is manual...

Here's the confession. Its half manual, half automatic. It
doesn't take a noticeable amount of time for me to manage,
but your mileage may vary. There are tools involved, but
nothing new -- you probably already have xml2rfc, rfcdiff,
make, scp, cvs, and emacs (gasp!).

I have found the per issue diff system very useful. Before
I start an edit it write the issue number in a file and
give a command. After I'm done editing I give another
command, which simply compares the end results from before
and after the edit using rfcdiff [1] and automatically
copies the file to my web server using scp. Text file
generation goes through xml2rfc [2] and a set of additional
small scripts that look for id nits violations etc.
The makefile handles all updates -- .txt, .html, main
diff, per issue diffs, tarball to the web based on
changed files.

I maintain the top level issue .html file manually,
including inserting links to diff files. I also maintain
the per-issue discussion files using copy paste... this
takes some time. All copying to the web server occurs
automatically, however.

 From the point of view of learning something from this
example, there are probably three aspects:

  o  The system used to manage issues. Many IETFers
     probably prefer a more graphical user interface
     and complete issue management system. Even I
     do, because I don't like copy pasting. (But
     see below for the third bullet -- I find some
     of the issue tools too hard to use.)

  o  Managing edits and per-issue diffs. Like I said,
     I have found this to be a very useful function.

     It could probably be accomplished also in the
     issue track software systems, with some additional
     code. Say, you could submit a "before" draft to
     the system and when you are done editing you
     could submit the "after" draft, and the issue
     tracker would then be able to show the diff to
     users.

  o  I believe its really important to present the
     issue information in a manner that is easy for
     people to look at. People are lazy, they will
     not do a query, might not even scroll down the
     page... passwords, queries, many drafts per page
     are probably an overkill.

--Jari

[1] Henrik's rfcdiff: http://ietf.levkowetz.com/tools/
[2] Marshall's xml2rfc: http://xml.resource.org

---

From: Jari Arkko <[email-masked]>
Date: Wed, 11 Aug 2004 02:18:55 +0300

> per sub-version of the draft, and generate an accompanying diff based

This hasn't been a big problem for me. I mean of course solving
the issue itself is the big challenge, but tracking the result
or sub-versions have not been a problem in my case. I don't actually
see sub-versions under my system. The stuff gets copied to web
as I do the edits, and edits get credited to the right issue.

But I do my edits sequentially, one issue at a time. In a few
cases the resolutions were not stable or my edits were not good
and I had to return to the same issue again. This is not a problem
unless I have done some other edits in between. If I have, I just
listed two different diffs, or created another issue number.

(In theory, I could actually do my edits in parallel, too,
everything gets automatically put to CVS and tagged with
issue numbers. However, so far I have not attempted to
extract the information from the version control system;
I suspect colliding edits would break some fraction of
the resulting per-issue draft versions.)

--Jari

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 11 Aug 2004 01:27:12 +0200

> as I do the edits, and edits get credited to the right issue.

Maybe you could send me a brief sketch (offline) of how you have
set this up?  I'm wondering of course if this can be put in a
shape to provide as a web service or downloadable tool...

> listed two different diffs, or created another issue number.

Yes.  But you're a very diciplined fellow :-)  I meant that
it's hard for a tool to enforce exactly this point.

> the resulting per-issue draft versions.)

Yes.  I remember we discussed this some time ago.

	Henrik

---

From: "Joel M. Halpern" <[email-masked]>
Date: Tue, 10 Aug 2004 19:34:01 -0400

It strikes me that telling authors that they must make changes atomically, 
and that they must produce diffs between each step, is asking the authors 
to do a lot more work.  For some working groups, this is probably not that 
big a deal.  For others (I am thinking of the last two rounds of changes to 
XCAP for example) it probably is not even well defined given the 
interaction among issues.
Yours,
Joel

---

From: Harald Tveit Alvestrand <[email-masked]>
Date: Wed, 11 Aug 2004 08:37:38 +0200

Nice discipline!

if comparing to the way I work, one important addition would probably be a 
function to mark an issue "Overtaken by Events" - ie if I get a complaint 
about the grammar of a sentence, and decide to remove that whole section 
due to another issue, the result of the issue needs to be marked "OBE".

And of course we have the "offline problem" - dealing with 20 issues while 
on an airplane, and not being able to produce the intermediate files on the 
webserver. Of course, that is solvable too.... 
see<http://www.computerworld.com/mobiletopics/mobile/story/0,10801,77600,00.html>

:-)

                         Harald