Re: [office] Approach to Disposition of Comments and Defect Reports

[robert_weir@us.ibm.com]

"Dennis E. Hamilton" <dennis.hamilton@acm.org> wrote on 12/08/2008 
11:22:35 AM:
> 
> PROVIDING DISPOSITION INFORMATION AND ERRATA
> 
> 4. IMPORTANT: Our only knowledge of the SC34 defect reports is 
> second-hand via access to the reports on the SC34 site and being 
> told about them by people who go to JTC1 and SC34 meetings.  We have
> no formal delivery of these items from OASIS to the ODF-TC so that 
> we may work on them in some formalized, official capacity.  We 
> should fix this.  It would also allow OASIS to acknowledge to JTC1 
> that this has been done and the next step will be our disposition 
> response.  (One thing that transmittal to the ODF TC could carry is 
> specification of an agreed deadline for an initial disposition 
> assessment and the ODF TC could respond with its commitment to a 
> response date.)
> 

The official mechanism is for SC34 to submit defect reports to the ODF 
TC's public comment list.  SC34 has been reminded of this request on more 
than one occasion.  This is far better than posting on a password 
protected SC34 website that few of us have access to.  (Heck, even today I 
can't seem to get access to the SC34 documents.  They seem to have changed 
the password and the new password has yet to trickle down through the 
multiple levels of international bureaucracy.)

> 5. Disposition responses will indicate our initial categorization 
> and screening, so that the contributors can tell what action if any 
> is to be taken, and when they might see a result. 
> 

All comments, whether from SC34 or from the public, should be recorded and 
classified.  The classification, whether editorial or technical, can 
sometimes be controversial.  So the classifications should be approved at 
the same time the proposed resolutions are approved by the TC.   The whole 
approved set of data (the defect, the classification, the proposed 
resolutions) we can call the proposed "Disposition of Comments" should 
posted at a fixed, publicly accessible URL.  We should put a link to that 
URL on the TC's home page.  We could also post a monthly reminder note to 
the comment list indicating this URL, as well as other administrivia 
regarding public comments, errata, etc.  Anyone who wants to know the 
status of a given comment can check the document at the given URL.

So it might look like this:

a) comments come in to comment list from wherever
b) someone (me?  you?) is assigned to transcribe the comments into the 
spreadsheet and record basic metadata, such as proposer, date, part and 
section numbers, etc.
c) We put on the TC agenda (as we have been doing) time to discuss and 
process new comments on the spreadsheet.  The TC would determine the 
classification and resolution, which would be recorded and published.

> 6. Errata documents will be produced as required and as permitted 
> under the OASIS TC Procedures.  The Errata documents will indicate 
> sources of the items and also, if we provided roll-ups in the Errata
> documents, which version of the errata document the item originated 
> in (unless modified subsequently).  This allows reviewers and users 
> of Errata documents to have single documents for a version of the 
> OASIS ODF Standard and be able to determine which items are new or 
> changed since the previously-approved Errata document.
> 

We need to check on whether this is allowed, but I agree it would be 
preferable to append to our current ODF 1.0 Approved Errata document than 
to create multiple ODF 1.0 Errata documents.  But each version of ODF (ODF 
1.0, ODF 1.1, ODF 1.2) should have separate errata.

> 7. A working draft Errata document will be kept in our document 
> store for ongoing review by submitters and others who want to see 
> what the provisional resolution of items via Errata is proposed to be.
> 

That would be ideal. 

> ENSURING TREATMENT OF DEFECTS IN FUTURE VERSIONS
> 
> 8. The Public comment list and all errata items must be screened 
> with regard to their treatment, if any, in later versions of the 
> OASIS Standard for ODF.  It is particularly important that those 
> defects that were not resolved in ODF 1.1 be resolved in ODF 1.2 as 
> much as we are able to do so.  We should give priority to that 
> determination once we have the complete lists at (3).
> 

In particular, defects reported against ODF 1.0 may or may not also be 
defects in draft ODF 1.2.  We've been trying to check this for each 
reported defect, and that is noted in the spreadsheet.  We want to ensure 
that no defects magically reappear in ODF 1.2 after being fixed in ODF 1.0 
errata.  It is probably easier to just plan on checking the approved 
errata against ODF 1.2 during the ODF 1.2 public comment period.  This 
will be faster and simpler than devising a process to prevent such errors 
from occurring in the first place.

> QUESTIONS
> 
> 9. We can "prune" the list of public comments, splitting out those 
> for which additional action is not required.  These can go into an 
> archive version of the document.  This will keep the list manageable
> and easier to review.  Is that acceptable in the future when we have
> a large number of resolved comments?
> 

You can also use spreadsheet "filters" to filter the view according to 
criteria.  Also, maybe this all gets moved into JIRA at somepoint, so we 
have a more flexible system?  It looks like JIRA has CVS import 
capabilities, so we should be able to bulk load items from our spreadsheet 
into JIRI, provided we stick to a one-row-per-comment design.  JIRI would 
also be good for more complicated workflows, such as a comment needing 
additional research by a TC member.

> 10. We do need to decide whether we will keep updating a single 
> errata document for a given OASIS Standard or will we produce 
> supplements to previous ones.  My recommendation is to keep complete
> roll-ups of errata items, so that a next Errata (i.e., for 1.0) 
> would replace the previous Errata.
> 

I agree.  If allowed, better to have the single errata document per ODF 
version.

> 11. We don't have any errata document for 1.1 and we also don't know
> what defects that apply to 1.0 and 1.1 will turn up in the 
> finalization of ODF 1.2.  We need a way to capture those items well 
> enough so they are not lost and that we can determine whether to 
> incorporate in 1.0 and potential 1.1 errata in the future.  Is it 
> correct that we are not committed to further formal errata for 
> either 1.0 and 1.1, but we want to be in a position to issue them as
> we might decide later?
> 

There is no requirement to produce future errata. But the TC certainly has 
the option to do so.  We are required to responding to defect reports from 
SC34, but in theory could simply be a Disposition of Comment report that 
says we have decided to defer the fix until ODF 1.2, or later.  I'd 
recommend something in the middle, where we prioritize our efforts.

Consider ODF versions, where N is the most recent OASIS approved version, 
and N-1, N-2, etc., are previous OASIS approved versions, and N+1, N+2 are 
future versions.

We should probably give most of our maintenance attention to version N for 
fixing defects, and version N+1 for technical revisions (new proposals). 
We should spend very little time on fixing editorial defects in version 
N-1.

> 12. I am also assuming that we will not obsolete 1.0 and 1.1 any 
> time in the near future and maintenance remains a consideration, 
> especially for 1.0 with its ISO/IEC IS 26300:2006 counterpart.  Is 
> that a fair assessment at this point?
> 

OASIS has no procedure for making an approved standard "obsolete".  JTC1 
can vote, I believe 5 years after a standard is approved, to "stabilize" 
it, meaning to declare that it will not be maintained further.  Also, 
although I am not sure whether this is procedurally valid, I've seen 
revisions of Ecma Fast Tracks in JTC1 carry language on their cover sheet 
like "This fourth edition cancels and replaces the third edition."  It is 
probably premature to consider any of these options, although if after ODF 
1.2 is approved, we look around and see that no one is using ODF 1.0 
(version N-2) then that is something to consider.

>    -   -   -   -   -   -   -   -   -   -
> 
> I am sure that more questions and aspects will come up.  Feedback 
> will be very helpful.
> 
> 
>  - Dennis
> 
> Dennis E. Hamilton
> ------------------
> NuovoDoc: Design for Document System Interoperability 
> mailto:Dennis.Hamilton@acm.org | gsm:+1-206.779.9430 
> http://NuovoDoc.com http://ODMA.info/dev/ http://nfoWorks.org 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 
>