Some communications with Toby yesterday reminded me that I missed a key point in the process I described: the creation of working drafts posted to OASIS to capture the progress. So the process I described should
be amended as follows:
1.
Create and process pull-requests for any “work in flight” changes you are currently working on. Create the PRs, run them through working meetings for agreement, and apply them. That way those changes can be discussed with clear visibility.
2.
Declare a WD and post to OASIS
3.
Once other PRs are approved and applied, address the restructuring effort by itself as an independent PR while no other PRs are pending. That way other changes aren’t lost in the big shifts of restructuring
4.
Declare a WD and post to OASIS
5.
Resume work on other changes by creating PRs against the restructured document.
The revision history for the WD at step 2 should reflect the work-in-flight changes; the revision history for the WD at step 4 should reflect reorganization to match the new OASIS document outline.
Dave
David Lemire
IA Systems Engineer
Technical Solutions
302 Sentinel Drive | Annapolis Junction, MD 20701
Work (301) 575-5190 |
Mobile (443) 535-1182
From: Lemire, Dave (HII-TSD)
Sent: Monday, April 12, 2021 1:30 PM
To: Toby Considine <toby.considine@unc.edu>; Duncan Sparrell <duncan@sfractal.com>; dj (dj@sfractal.com) <dj@sfractal.com>; Brule, Joseph M. (Fed) <joseph.brule@nist.gov>; Alex Everett <alex.everett@unc.edu>; 'vasileim@ifi.uio.no' <vasileim@ifi.uio.no>;
Dave Kemp <dk190a@gmail.com>; 'martifev@ifi.uio.no' <martifev@ifi.uio.no>
Cc: TC OpenC2 <openc2@lists.oasis-open.org>
Subject: Updating Work Products to New OASIS Document Template
The TO: addressees on this email are identified as document editors in our
work products list; I’m cc’ing the TC list for general awareness.
I’d like to call our editors’ attention to the need to update your work products to the latest OASIS document template. The TC’s latest starter document was for the
anti-virus AP. That document uses the latest OASIS template. Changes from older templates are roughly as follows:
Several of the main sections are now included as Appendices. For instance, the Security Considerations is now a part of Appendix B, "Safety, Security and Privacy Considerations". Also, you'll find that the References are now an appendix (A), and also the section
"Non-Normative References" has been retitled as "Informative References. (Appendix A.2). There are other fairly minor changes in the wording of Notices (also mostly moved to an Appendix), and the "IPR Policy" (usually 1.1) is no longer a part of the template.
In checking with TCADMIN I received the following guidance:
New stages of your existing specifications don't have to be modified to use the new templates, but you should be using the "2020style" for any new work, including new Version numbers of the existing specifications.
That means new CSes of our three approved specifications don’t need reformatting, but
all of our other work products do, as do new versions (e.g., 2.0) of our three approved specs. My experience with the MQTT specification was that it was an hour or two of work to do the basic re-arranging but you also need to allow some time for
a quality control pass, updating internal links, etc.
As noted at last week’s working meeting: re-arranging a document like this swamps out visibility of any other changes, so the work product editors are requested to do the following:
1.
Create and process pull-requests for any “work in flight” changes you are currently working on. Create the PRs, run them through working meetings for agreement, and apply them. That way those changes can be discussed with clear visibility.
2.
Once other PRs are approved and applied, address the restructuring effort by itself as an independent PR while no other PRs are pending. That way other changes aren’t lost in the big shifts of restructuring
3.
Resume work on other changes by creating PRs against the restructured document.
Please factor this requirement into your plans for developing your work products. Thanks.
David Lemire
OpenC2 TC Secretary
David Lemire
IA Systems Engineer
Technical Solutions
302 Sentinel Drive | Annapolis Junction, MD 20701
Work (301) 575-5190 |
Mobile (240) 938-9350