Structured/semantic revision history

[ronaldtse]

The revision history may be better served in a semantic format since they are being used by NIST and OGC, in the same line of thought of machine-readable revisions. At least, they can be rendered in a consistent format.

Some OGC documents (not all) contains a “Revision History” section either in the preface or in the annex (supposed to be the last annex before the bibliography). They are all expressed in some table form but without a fixed format.

The OGC official structure and location from @ogcscotts:

Yes, we need a consistent format. The official format is: | Date | Release | Author | Paragraph Modified | Description

The history should always be in an annex before the bibliography.

Previously there were:

|Date |Release |Authors |Paragraph modified |Description
|04/02/2012 |Draft |R Thakkar |All |Original draft document

|Date |Release |Editor | Primary clauses modified |Description
|2017-10-09 |3.0.0-SNAPSHOT |C. Portele |all |initial version

| Date | Version Doc. | Editor | Description
| 2002-08-30 | 0.1 02-077 | Kurt Buehler | Initial version of ORM. Doc OGC +
George Percivall, Sam Bacharach, Carl Reed, Cliff Kottman, Chuck Heazel, John Davidson, Yaser Bisher, Harry Niedzwiadek, John Evans, Jeffrey Simon

| _Date_ | _Release_ | _Author_ | _Description_
| 2018-06-04 | 1.0 | Gabby Getz | Put 3D Tiles specification document into OGC document template

We should also support the difference between the Editor and Author roles in every stated change.

This task is to come up with a defined syntax for structured revisions.

[ronaldtse]

Maybe something like this:

change = {
  date: /* date */
  version:  /* release */
  contributors: [ { role: author, … } ] /* author, editors */
  locality_description: [] /* paragraphs modified */
  change_description: [ text ] /* description */
}

In the future, locality_description and change_description can be:

  changes: [ text or patches ]
  locality: [ locality indication ]

The input syntax may be a table or in sections, something like:

[revisions]
== Revision history

=== 2018-06-04; 1.0; Gabby Getz (author), R Thakkar (editor)

Paragraph 3.1:: Put 3D Tiles specification document into OGC document template

Paragraph 5:: …

=== 2018-07-05; 1.1; ...
…

[opoudjis]

NIST by contrast is:

[.errata]
|===
|Date |Type |Change |Page

|2019-01-01 |Minor |Repaginated |1-12
|===

[ronaldtse]

NIST and OGC revisions can certainly be harmonized, since they are both about document changes.

[opoudjis]

If OGC errata are not conformant the errata gets entered in a preface/annex like before.

[opoudjis]

Any such table needs to be rendered with single boundary.

[rggibb]

@ogcscotts While ISO documents don't formally have a revision history as an annex, all standards that are published as jointly by OGC & ISO experience the ISO pre-publication cycle as well as the OGC cycle. So with that in mind, I can identy three levels of release cycle:

• international publication: these are the OGC and ISO published standards,
• managed releases: documents go through a number of iterations of comment and ballot (eg the ISO progression from CD->DIS->FDIS->IS), and also corrigenda or errata may be elevated as minor changes to published standards
• further cycles of revision as the WG or SWG develops their ideas.

Comments received in the ISO managed release cycles, are all numbered and a formal response is provided back to the community acknowledging how the comment was addressed. I understand it is not unusual to receive in excess of 100 comments. So to assist my management of the resulting changes, where relevant I started description field with the comment number in bold. eg DK001, and I tried to use the same description text in the comment for the git commit .. in other words I would write the entry to the revision history annex, and then copy/paste the description to the commit comment.

My personal rule-of-thumb for iterating the minor revision nymbers was to increment by one whenever there was a renumbering of the sections. Of course when that happens the paragraph numbers referred to in previous entries to the revision history are no longer pertinent to the current document .. and I made no effort to refactor the paragraph numbers, which I had hardcoded, not entered as asciidoc references.

Thinking retrospectively, what I should have done, but didn't do rigorously, was formally publish appropriately numbered git releases associated with all the releases identified above.

I note also at this point that the ISO and OGC templates of a single document have different top level numbering. So that further complicates keeping track of changes, and raises the question of whether the paragraph numbers should refer to the OGC or ISO template, or whether they can be managed in a single .adoc file.

I note that OGC/ISO TC211 are currently clarifying how to run 'joint' projects, and the practice seems to be settling on a cycle of iterations that alternate between phases under OGC management and phases under ISO managament , so there are defined hand-over points where the changes are driven by OGC protocols or ISO protocols, so at any one time the live document is essentially under the management of one organisation or the other. At the moment for instance, while the DGGS document is under ISO/DIS ballot, and OGC public comment, the comments gathered by OGC will be fed into the ISO/DIS ballot's comments, so the process influencing changes is being driven by ISO protocols. What I'm saying here is that within each phase changes are entered into the revision history from either the OGC or the ISO template, but rarely both. The exception is that there are some portions of the document that may exist in only one template and not the other, and that changes to those portions are therefore unique to that template.

I'm raising these as discussion points, to see if there are ideas that can be formalised and or automated, and not requesting specific implementation.

[ogcscotts]

@rggibb Excellent synthesis of how the document evolve (and interesting to hear where you typically minor-revision drafts). Given that ISO does not actually publish a revision history (at least not that I have seen), we could probably just tie the entries to the OGC numbering and have more general entries for edits accompanying ISO process edits. If we always have Block IDs in the Asciidoc source, then reference could just be to those IDs.

[ronaldtse]

Sorry for the late reply here, somehow I thought I already replied...

(@rggibb) What I'm saying here is that within each phase changes are entered into the revision history from either the OGC or the ISO template, but rarely both. The exception is that there are some portions of the document that may exist in only one template and not the other, and that changes to those portions are therefore unique to that template.

This is good insight. I think the consequence here is that there are (a) shared revision changes but also (b) unique revision changes per publishing party (say, X and Y). The standard as published by X should contain the (a) changes and also (b) changes that apply to X's content.

If we always have Block IDs in the Asciidoc source, then reference could just be to those IDs.

The challenge here is that the blocks (and hence the anchor/ID) can be deleted -- in that case the reference to the deleted anchor/ID in the revision history has to be made concrete (i.e. from <<clause5-1>> to Clause 5.1).

We have recently developed a mechanism for specifying locality (from the machine-readable amendment work), so we could re-use that here, when clauses are removed, e.g. clause=5.1,paragraph=1.

---

In sum I believe we have a case here because we can align OGC revisions with those from NIST and IHO.

[opoudjis]

Needs prototype, needs analysis of revision history across Metanorma flavours, need to ensure unchanged rendering.

[ghobona]

OGC Staff briefed on 2023-09-04.

[opoudjis]

Refer https://github.com/metanorma/metanorma-iho/issues/15

[opoudjis]

The encoding scheme we will use is in https://github.com/metanorma/metanorma-bsi/issues/286. Because it involves specifying of document versions as bibliographic objects, the information about each version is whatever can be captured bibliographically, including draft identifiers and draft dates, corporate authors, and document stages; so @rggibb ’s proposals can be addressed in principle. Without a sample document or a requirement for rendering, I'm not going to essay a sample encoding.

The current and previous encodings are:

The official format is:
| Date | Release | Author | Paragraph Modified | Description
| D       | R            | A          | P                                | D 

The history should always be in an annex before the bibliography.

Previously there were:

|Date |Release |Authors |Paragraph modified |Description
|04/02/2012 |Draft |R Thakkar |All |Original draft document

|Date |Release |Editor | Primary clauses modified |Description
|2017-10-09 |3.0.0-SNAPSHOT |C. Portele |all |initial version

| Date | Version Doc. | Editor | Description
| 2002-08-30 | 0.1 02-077 | Kurt Buehler | Initial version of ORM. Doc OGC +
George Percivall, Sam Bacharach, Carl Reed, Cliff Kottman, Chuck Heazel, John Davidson, Yaser Bisher, Harry Niedzwiadek, John Evans, Jeffrey Simon

| _Date_ | _Release_ | _Author_ | _Description_
| 2018-06-04 | 1.0 | Gabby Getz | Put 3D Tiles specification document into OGC document template

The encoding is going into the preface, as all document metadata does; "misc-container"/"metanorma-extension" preface clauses are strictly metadata, and are not rendered. This encoding will be used to populate the final annex in Presentation XML. I am not currently going to implement a different placement of the document history.

I am putting "whole" as the location for modifications in the following, as this is the reserved Metanorma term for specifying the entire document in existing markup.

[.preface]
== misc-container

=== document history

[source,yaml]
----
- date:
  - type: published
    value:  D
  version:
    draft: R
  contributor:
    person:
      name:
        abbreviation: A
  amend:
    location: P
    description: D
- date:
  - type: published
    value:  2012-04-02
  version:
    draft: Draft
  contributor:
    person:
      name:
        completename: R Thakkar
  amend:
    location: whole
    description: Original draft document
- date:
  - type: published
    value:  2017-10-09
  version:
    draft: 3.0.0-SNAPSHOT
  contributor:
    person:
      name:
        completename: C. Portele
  amend:
    location: whole
    description: initial version
- date:
  - type: published
    value:  2002-08-30
  version:
    draft: 0.1 02-077
 contributor:
    - person:
       name:
          completename: Kurt Buehler
       role:
         type: editor
    - person:
       name:
          completename: George Percivall
       role:
         type: editor
    - person:
       name:
          completename: Sam Bacharach
       role:
         type: editor
    - person:
       name:
          completename: Carl Reed
       role:
         type: editor
    - person:
       name:
          completename: Cliff Kottman
       role:
         type: editor
    - person:
       name:
          completename: Chuck Heazel
       role:
         type: editor
    - person:
       name:
          completename: John Davidson
       role:
         type: editor
    - person:
       name:
          completename: Yaser Bisher
       role:
         type: editor
    - person:
       name:
          completename: Harry Niedzwiadek
       role:
         type: editor
    - person:
       name:
          completename: John Evans
       role:
         type: editor
    - person:
        name:
           completename: Jeffrey Simon
        role:
          type: editor
  amend:
    description: Initial version of ORM. Doc OGC
- date:
  - type: published
    value:  2018-06-04
  version:
    draft: 1.0
  contributor:
    person:
      name:
        completename: Gabby Getz
  amend:
    description: |
      * Put _3D Tiles_ specification document into OGC document template
      * Miscellaneous updates
----

[opoudjis]