Establish CHANGELOG and "releases"?

[yarikoptic]

I know that it sounds odd but since dandi-infrastructure is used by derivative efforts (LINC and EMBER), those teams (and DANDI people in a few weeks after) would appreciate from having a conventional track of changes and description of rationale for them. Since auto is doing a decent job in populating CHANGELOG and linking to PRs etc, I would suggest us to

• adopt time based versioning like git-annex does where it would be

  {MAJOR}.{DATE}.{PATCH}

  • MAJOR - to increment only when backward compatibility gets "broken" as a service gets removed or alike
  • DATE - the date for release
  • PATCH - if needed on top of DATE

  @jwodder -- can auto or something else implement such version minting based on labels?

• automate "releases" which would simply mint a new version from master and update CHANGELOG. Pretty much any PR, unless bundling multiple changes together, could have its own "release"

• PR titles should be descriptive enough to summarize the change, and extended description should provide some context for the change: "why and how"

Overall, it

• it should not add extra burden - labeling is easy
• produce summary CHANGELOG for folks to consult/navigate upon merges into their solutions
• allow downstream projects to reference specific state of deployment based on the release labels ("upgrade infrastructure setup from 1.20250101.0 to 3.20250217.0 of DANDI ...) instead of "sync to DANDI from our prior sync 2 months ago")

WDYT @waxlamp @satra et al?

[jwodder]

@yarikoptic I don't think auto can do date-based versioning.

[waxlamp]

I agree that we can do a better job of using descriptive PR titles and descriptions in order to explain why certain changes are being made (such as #211, where we were already manually maintaining ImprovMX resources, and this change just brought that management under the TF umbrella).

However, I don't think putting in tooling to generate changelogs and releases would be worth the effort and maintenance burden. Since we make all changes through PRs (now with an increased commitment to better descriptions, etc.) anyone can simply look through the merged PRs to see the trail of changes that has been made.

Beyond that, as Terraform is a declarative description of the current state of the infrastructure, looking at the current state theoretically tells you all you would want to know about the setup. I think a better PR discipline along with consulting the DANDI team whenever there is a question should be a good general solution for improving understanding and communication across the various archives.

[yarikoptic]

Since we make all changes through PRs (now with an increased commitment to better descriptions, etc.) anyone can simply look through the merged PRs to see the trail of changes that has been made.

sure, but without a CHANGELOG collecting them for specific points (releases) it is not clear which PRs are relevant from prior point in time.

That is why I thought that CHANGELOG.md with brief items (titles of PRs) with pointers to related PRs (with extended docs) would be kinda optimal balance.