Handle SP amendments

[strogonoff]

Proposed way:

1. Store normalized SP data in this repository (ITU OB data).[0]

2. Expose a GUI for editing this SP data in ITU OB Editor app. ITU representative would be able to edit SP at any time, whenever new information comes in.

3. Make amendment entry zero-input. ITU representative selects an SP dataset, and everything else is handled by the app. The app reads dataset state from the commit corresponding to previous OB publication date, calculates a diff with the current working tree version of the dataset, and adds amendments in RFC 6902 format.

[0] In future move SPs into their own repo(s)

[strogonoff]

Using the tool for diffing JS objects: https://github.com/benjamine/jsondiffpatch

[ronaldtse]

Each SP modification must be in a defined "amendment object" for every change to a SP dataset.

An amendment:

• includes metadata - e.g. who initiated this amendment, where this amendment instruction was taken from (e.g. telecom operator)
• may contain multiple JSON patches
• is applied on an SP dataset
  • "SP with amendment applied" is not "SP dataset and amendment" separately, just like how Git commit contains other metadata (incl. commit message, signatures) vs the code that a Git patches applied on.
• allows full rendering of display text of this amendment inside an OB issue

[strogonoff]

Editing dataset directly doesn’t preclude any of the above. It’s the question of GUI, and GUI that implements change management by exposing a sequence of patches, rather than the dataset directly, may be extremely complicated and inconvenient to use.

(Imagine adding amendments on top of amendments, and on top of that correcting erroneous amendments that have other amendments added afterwards.)

[ronaldtse]

It’s the question of GUI, and GUI that implements change management by exposing a sequence of patches, rather than the dataset directly, may be extremely complicated and inconvenient to use.

It's not only the GUI but the data representation. We need the changes to be expressed explicitly for every amendment. This is the same for IEC and ISO standardization items. Each change must be expressed explicitly (unless we are talking about "replacing with a full object").

(Imagine adding amendments on top of amendments, and on top of that correcting erroneous amendments that have other amendments added afterwards.)

• Dataset A + Amendment 1 => Dataset (A with 1 applied)
• Dataset (A with 1 applied) + Amendment 2 => Dataset (A with 1 and 2 applied)

We do not need to support Amendment + Amendment.

[strogonoff]

Dataset (A with 1 applied) + Amendment 2 => Dataset (A with 1 and 2 applied)

We do not need to support Amendment + Amendment.

If amendment 1 contained a typo discovered before the next ITU OB was published, “Dataset (A with 1 applied)” is no longer a thing. Replacing Amendment 1 with Amendment 1.2 means Amendment 2 would have to be applied to “Dataset (A with 1.2)”.

We can’t simply reapply Amendment 2 as is. If Amendment 1 is “remove row 123”, Amendment 1.2 is “remove row 125”, and Amendment 2 is “remove row 124”, then Amendment 2 would result in a wrong row being removed. We would need the user to re-add all amendments following Amendment 1.

[strogonoff]

There are often multiple amendments to a given SP between ITU OB issues. An “amendment message” as published in ITU OB is not an amendment; it contains multiple factual changes, coming from different telecom operators.

For example, this amendment message represents three “atomic amendments” coming from three different carriers in Germany. This message has multiple changes coming from multiple countries.

[strogonoff]

I have an idea of how to implement it, let’s see if it works.

[ronaldtse]

For example, this amendment message represents three “atomic amendments” coming from three different carriers in Germany. This message has multiple changes coming from multiple countries.

Can we consider these as multiple individual messages inside an OB?

[strogonoff]

With the legacy form of OB, adding an “amendment message” for each individual change to SP would make the document much less readable. (Remember, a message takes a whole page at least.)

So, unless we are getting rid of existing deliverables (paged MS Word/PDF documents) or thoroughly revamping their content structure[0], we should probably combine multiple changes to an SP into one amendment message for now.

Thankfully, those are two different things anyway. Updating ITU dataset is one thing. Creating an appropriate amendment in the next upcoming OB issue describing the changes that took place is another thing.

I believe the app should give the facility to edit ITU datasets, and easily create appropriate amendment messages without having to re-enter the data.

[0] Since those docs are essentially ITU’s interface to external parties, they probably wouldn’t be happy if we just did that unilaterally.