[Ccsds-omg-liaison] Preliminary AB Review: Command and Control Message Specification (C2MS) 1.0 FTF report

[Elisa Kendall]

Hi Jay and all,

Here is my initial review of the C2MS FTF Report.  I think it was a nice 
attempt for someone who is new to the process, but there are a few 
things to address and/or at least discuss in Reston.

Document check:

Command and Control Message Specification (C2MS) 1.0 FTF report     
dtc/19-02-08
Convenience document clean        dtc/19-02-09
Convenience document with change bars        dtc/19-02-10
C2MS zip file for XML schemas        dtc/19-02-12
C2MS MagicDraw (.mdzip) for UML model        dtc/19-02-13
C2MS XMI of the model file for UML model in the specification     
dtc/19-02-14

1. Report.  The voting record is clear, report appears to be well-formed 
and issues were clear, aside from my comments, below.
Like another report I reviewed, there was no zip archive for attachments 
- this is only possible if there were no changes to diagrams, etc.  
Several diagrams changed, however, so I would have anticipated either 
(1) that the replacements would have been attached to the issue 
resolutions, or (2) that you would have a separate, ancilliary diagram 
archive, that includes them.

Given that it appears the source for the specification is MS Word, and 
that the diagrams in the document are likely .png or .jpg rather than 
.svg (OMG requires vector graphics for the final publication), we will 
need an archive for those that changed, or possibly for all diagrams in 
the specification, in .svg format, for the published version of the 
specification.  If you need assistance in doing this in MagicDraw, let 
me know. You'll need an additional document number for the diagram 
archive from Juergen, and to revise the report, referencing that 
additional archive. There is an unused document number allocated to C2MS 
for an ancillary attachment file - if you don't need to revise anything 
else, you could use that document number for your images and Juergen can 
change its description and name on the server.  But, see below - I think 
that there should have been attachments in cases where you said 'see 
change barred document' or 'see word document', since people do have to 
vote on the changed text.  If you can explain how that was done, for 
example if you emailed the change barred text to team members prior to 
voting for review, then we might give you some slack there, but I'm not 
comfortable with what I found in the report alone.

There were 14 issues that were deferred - was this due to a need to 
publish a report/specification within a certain time frame? The FTF was 
chartered in June 2018, so theoretically this FTF could have run until 
the Amsterdam meeting, with the possibility of continuing with an FTF 2 
for up to another year.

2. Individual Issue Resolutions.
(a) Shouldn't the text in C2MS-8, 3rd and 4th changes, read "REQUEST-ID 
in the associated REQ message" instead of "REQUEST-ID the associated REQ 
message"?  It was identical in the voted resolution to what was done in 
the specification change, but ... (if you decide to correct this, it 
would require changes to the report, change barred and clean documents, 
probably a nit that can be dealt with editorially rather than requiring 
another vote).

(b) In the change barred spec, the change in section 8.1 regarding 
extensions is marked C2MS-10 and should be C2MS-12.

(c) There were several cases where there were no editing instructions, 
just a note to defer to the change-barred specification.  This doesn't 
provide an easy way for a reviewer to tell if the right thing was done 
or not, or whether you missed anything or not.  C2MS-23 is a case in 
point, where some significant changes were made, including the addition 
of a whole section, a new table, etc.  If the change is too large to do 
in the context of solitaire/JIRA, it should be documented in a Word or 
Libre Office or other document and attached to the resolution for that 
issue. The attachment will show up in the archive for the report so that 
an AB member and/or OMG editor can see what was required and ensure that 
the change that was voted on was applied appropriately.  Without that 
record, it's hard to know what the FTF or RTF approved.  They may have 
approved the change in general, but really would have to see the 
proposed language and technical content to ensure that they agree with 
that and to provide the record for the AB and OMG editor to use when 
revising the formal specification.  I'm not sure that it makes sense to 
ask you to go back and recreate this paper trail, but ...  C2MS-24 is 
similar, and even says that one person changed the text, someone else 
changed the UML, but none of that was attached to the resolution, so I 
can't really tell what was approved
by the FTF.  If everyone on the FTF participated and the content was 
reviewed in task force meetings, that should be documented and the 
resulting modifications should be provided in an attachment so that 
anyone could review it and apply those changes to the original document 
to get the resulting version, ensuring that what people voted on is what 
happened.

(d) There was at least one case where I could not find the issue number 
tag in the document, e.g. C2MS-25, C2MS-36.  In the case of C2MS-25, I 
only found DEVICE.n.PARAM.m.VALUE once in the document and there was 
nothing changing it from binary to variable ... the Value/Description 
column was blank in Table 8-53 and nothing in the Notes column said 
anything about the type ... was it removed by another issue and I missed 
that somehow?

(e) C2MS-41 was listed as deferred, and I did not find it in the 
convenience doc, but it looks like it was resolved from the description?

3. All references to 'http' in the XMI file should be 'https' -- I 
didn't attempt to validate this otherwise, though.  You'll need to 
correct this and get a new number from Juergen for the revised XMI 
document, which will then require a change to the report.

Please feel free to reach out if you have any questions. We can set up a 
call for next week to walk through this as needed.

Best regards,

Elisa