Important information for CHANGELOG

[richb-hanover]

@aljazerzen @max-sixty @snth @ALL...

I just created a PR to update the CHANGELOG so that it contains critical info for each change. See PR #1582

I think we're planning only to keep one "unreleased" version, so I removed the "0.5.0 release" header, and moved the new switch info to the "0.4.2 Unreleased" section.

Going forward, having all the following info in one place (the CHANGELOG) will simplify the process of "pulling the trigger" for every new release:

• A description of the change. (I really liked the examples for the new from_text function)
• Extra credit for an overview of the syntax
• A link to any Issue or Discussion that gives context
• Cite the authors for new features
• Add Breaking change: in front of the item if required
• A (Implemented in Playground) notation where this is the case

Thoughts? Thanks.

[max-sixty]

I think this is excellent. Would you be up for adding to DEVELOPMENT.md?

The only thing I'd add is that we care most about development velocity, so adding entries is only required for large user-facing changes. It's welcome but optional for all other changes.

---

I'd still be up for something auto-generated. But I can't find any tool which includes GitHub handles (#736 has some links to options). I think that's fairly important — it's nice to be called out in public for good work — though maybe I'm overstating it.

The default GitHub release notes are decent and zero-overhead, and use GitHub handles — they list the commits, the PR, and the contributors. Ruff uses this: https://github.com/charliermarsh/ruff/releases. It offers no real commentary, and doesn't split the items into sections.

One option would be to use something like Release Please or GitHub's default for the long list of changes, and then have folks doing big features write something for substantial changes (or I can, if that slows folks like @aljazerzen down)

---

What does this final bullet mean?

A (Implemented in Playground) notation where this is the case

[richb-hanover]

I see multiple - potentially incompatible - moving pieces that we need to coordinate:

1. Language enhancements and evolution. In this experimental phase, these occur rapidly/frequently
2. Documentation, whether a quick overview, or carefully edited information in the Book
3. Test cases from "real live people": PRQL needs them to "prove out" the language. Testers try the new features to do useful work
4. Tooling and infrastructure to implement any of the above

First let me say that I am confident that we can design any production system (# 4 above) we desire. Our decision is whether the outcome justifies the effort, and whether the added work is a short-term fix, or will serve us for the long term.

Can we reserve time this Sunday on the Dev Call to consider these options? Thanks.

[max-sixty]

What do the four items represent? Are we still the changelog?

We can discuss some of this on the dev call, though ideally we'll have lots of topics of discussion...

[richb-hanover]

What do the four items represent? Are we still the changelog?

The changelog is only part of it. The bigger issue (which I was addressing above) is how we handle releases. Let me restate what is motivating my note:

Some people voiced the concern that the Playground and Book weren't in sync. This led to a flurry of suggested solutions: lock the Playground to the released versions; faster release cadence; build a parallel stable and development site; multiple versions (0.4.2 and 0.5.0); other thoughts. I staked out a position, but only to encourage discussion.

This is what I'd ask to discuss on the Dev Call. Thanks.

[max-sixty]

OK. I'll respond on that issue for the broader point.

For the changelog specifically, I thought your bullets were good — feel free to add those to DEVELOPMENT.md to give contributors guidance.