2025-04-16 Community Check-In: SeqJSON Comments

[cartermak]

Attendees

@cartermak
@ewferg
@tloreilly56
@shaheerk94
@goetzrrGit
@dandelany
@jmorton

Agenda:

• Open PRs
• SeqJSON comments
• Multiple sequences per file

Notes:

• Distinguish whether PRs are breaking changes (req. PMC approval) vs. test files, packaging, etc. (PMC Chair can merge alone)

SeqJSON Comments

Driving request: Users want comments to persist in SeqN when converted to SeqJSON. Lack of comments has been raised as one of the biggest usability issues. Want a way to persist all comments from SeqN in the SeqJSON so they're visible in SeqN generated from SeqJSON.

User flow: teams build in SeqN, but deliver as SeqJSON to MPST. After some processing by MPST (e.g., merging), teams must review the sequences, and do so by converting SeqJSON back to SeqN.

• Current behavior in Phoenix is mixed and confusing - inline comments persist, standalone comments don't. See Phoenix editor does not include line comment in SeqJSON output aerie-ui#1670
• Problem: no current place comments go in SeqJSON, unclear where comments should go
• Take: Best user experience is that everything persists, rather than dropping comments
• Info: The note step type exists, but has timing information which complicates the sequence. In SATF, you can omit timing information (equivalent to R0).
• Take: every step in SeqJSON should have a timestamp, even if it's R0
• Suggest: comments turn into @NOTE with R0
• Take: comments generally get lost when you convert/compile file formats. This round-trip issue is more of a process problem than a capability problem
• Take: SeqJSON is marketed as an interchange format, not a downstream format, so expected that we can round-trip, and so not acceptable to lose information between SeqN <-> SeqJSON.
• Info: VML users were unhappy when comments weren't persisted, so Seqgen now persists standalone VML comments using the note step with special metadata to mark it as a comment when converting to SATF; comments at the top level of the file don't persist; "inline" comments are tied to the specific command rather than their own step. Previous interchange format SML could also carry comments, but also didn't support header comments.
• Info: How is note used? One workflow is attaching timing information to generate a message in modeling to indicate an expected event
• Suggest: comments in the body of SeqN sequence would become steps with a zero relative time tag, and we either add special metadata to the generated note to indicate it's a comment, or add a new comment step type
• Problem: no clear home for comments that aren't interlaced with the steps (e.g., in the sequence header directives)
• Suggest: could have a special metadata key for seqn-comment, but then ambiguous whether a comment belongs to step above vs. below.
• Take: Clipper using SeqJSON as an interchange format now doesn't mean we should prioritize development of it as an interchange format moving forward.
• Take: Generally dislike SeqJSON being a centralized interchange format for all sequence languages
• Take: In spirit of drawing lines in the sand to not accept all user requests, could argue that this is the kind of accepted request
• Suggest: we should consider a different way to express "order" in SeqJSON
• Problem: comments complicate merging

Status:

• Eric/Dan/Parker/Taifun in favor of supporting a workflow where SeqN comments are persisted in SeqJSON and can be round-tripped back to SeqN. Carter/Shaheer dissent/concede
• Our tentative proposal: 1) special metadata key in top-level of sequence (e.g., sequence-comment) to capture top-level/header comments that don't belong to the ordered list of steps. 2) Comments below the header are treated as note-type steps with metadata to identify them as comments (TBR, could add comment step type) and timing of R0

Example SeqN:

# Top Comment 1
@ID "my_sequence" # Top Comment 2

# Top Comment 3

@LOCALS L000INT # Top Comment 4

# This becomes a step

R1 DO_SOMETHING # This becomes command description

# This becomes a step
R1 DO_SOMETHING_ELSE

# Comment at the end

Round-tripped:

# Top Comment 1
# Top Comment 2
# Top Comment 3
# Top Comment 4
@ID "my_sequence"
@LOCALS L000INT

# This becomes a step
R1 DO_SOMETHING # This becomes command description
# This becomes a step
R1 DO_SOMETHING_ELSE
# Comment at the end

Actions:

• Update governance
• Pick at SLIM PR for good ideas/close
• Clarify decision-making process - consensus-seeking, opportunity to dissent (and encouraged to document)
• Discuss proposal with Clipper stakeholders, gather more directed user feedback
• Finalize proposal
• Capture dissenting opinions