Provenance: Changelog

[ax3l]

After #184, another common need that is written as form-free comments in today's lattice files is a "changelog" of a lattice file.

Today, it is common to write a file top comment that documents changes/the history of a file. While not replacing version control, we could provide a more stringent form for this in an optional field changelog, e.g.,:

PALS:
  version: null  # PALS schema version (not yet defined)
  
  authors:  # optional but recommended for provenance
  - name: last, first
  - name: last2, first2
    # ...

  changelog:
  - date: 2026-02-25
    authors: [1]  # reference above list, 1-indexed, optional
    change: "Upgraded the magnets to include fringe fields effects."
  - date: 2026-01-10
    authors: [1, 2]
    change: "Added the booster."
  # ...

  facility:
    - ...  # lattice elements, beamlines, lattices, parameter set commands, etc.

[ax3l]

This (maybe with a different name?) might also be sensible for machine-generated lattice files, e.g., when we use PALS as the meta-data file describing a measurement... cc @roussel-ryan @ericcropp @lee-edelen?

Could be used to describe what was the intention / change in a batch of shots, etc.

[roussel-ryan]

I personally think that is out of scope for a PALS lattice, which only defines the facility, not the operations of a facility

[DavidSagan]

My view is that PALS should strive for maximum usefulness without sacrificing maintainability. So having a changelog sounds reasonable to me. One thought would be to have a metadata node under the PALS node to store stuff like a changelog. This would avoid "pollution" of the PALS node.

[ax3l]

@roussel-ryan thanks, good to know you won't need it for that task.

@DavidSagan The extra level would only add nesting, since the PALS root is already the intentional anchor for general metadata keys. Since it would be optional, it would not pollute general files and with a reserved clear key is also unlikely collide.

All that said, this is low priority for me. I just noticed that this is very common metadata for lattice files I work with.

[roussel-ryan]

Based on discussion on 3/4/2026 we should include this feature, either via a metadata field or under the PALS node. With the include nomenclature we can place longer changelogs in separate files as needed