More structured management of CHANGES.txt

[dweiss]

Description

There's been interesting patch in Solr that aims at making CHANGES.txt management better [1]. This file gets out of sync between branches all the time and is notoriously difficult to get right.

I'm not advocating to take the same approach as Solr did but it'd be nice to somehow:

• make it easier to verify that PRs put the changes entry in the right place (attach them to the right version),
• make the active-versions CHANGES.txt smaller and easier to view/convert to other formats.

Another alternative that I know of is to generate these from git logs but this requires some attention when formatting commit messages and may be hard to enforce.

[1] https://issues.apache.org/jira/browse/SOLR-17619

[rmuir]

@dweiss I'd like to throw out the built-in github functionality as another alternative.

To create a release I typically do gh release create "${GITHUB_REF_NAME}" --generate-notes. This is the same as checking the "auto generate release notes" functionality in the releases tab.

You can drive it based on a simple release.yml configuration file, which is driven by PR labels. example file I like to use which groups changes into two buckets only (so you get dependabot and non-dependabot groups):

# .github/release.yml

changelog:
  categories:
    - title: 🏕 Changes
      labels:
        - '*'
      exclude:
        labels:
          - dependencies
    - title: 👒 Dependencies
      labels:
        - dependencies

https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes

[dweiss]

Thanks, it's one of the alternatives worth considering.

[dsmiley]

The labels aspect is nice.

I wish GitHub PR had code review over a commit message, so we could ensure it's a good/reasonable one, and use that as an opportunity to potentially add metadata / structure that wold be useful in automated release log generation, like that GitHub generator thing. Can't change a commit once it lands on main!

I briefly reviewed https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes Does it use PR titles (which are editable), or first-line merged commit messages?

Solr's system has the benefit of a folder of changelog entries that can be browsed to get a sense of what changes have happened but not released, and potentially updated them later.

[rmuir]

It is not difficult to lint commit messages. The linters all kinda suck though.

- name: Checkout sources
  uses: actions/checkout
  with:
    fetch-depth: 0
...
- name: Validate PR commits with commitlint
  run: npx commitlint --from "${GH_SHA_FROM}" --to "${GH_SHA_TO}" --verbose
  env:
    GH_SHA_FROM: ${{ github.event.pull_request.base.sha }}
    GH_SHA_TO: ${{ github.event.pull_request.head.sha }}

[prudhvigodithi]

I have an idea, how about we simplify CHANGES.txt to track only the upcoming release version per branch?

Since the repo is already branched by version we can:

• main → CHANGES.txt tracks only upcoming version changes
• branch_10_3 → CHANGES.txt tracks only upcoming 10.3.x changes

Contributors can simply append to CHANGES.txt instead of searching through the entire file to find the right version section. Now we can use CHANGES.txt from that branch directly as release notes (no need to scan commits or PRs as the file already has exactly what's in this release).

Only catch here is to clear CHANGES.txt to start fresh for the next release, IMO we should be able to automate this with a workflow to create a PR with clearing CHANGES.txt on a release event. Clearing CHANGES.txt after release should be fine as the content is preserved in the tagged release.

So :

• Now since file is not too large users can just add content to the CHANGES.txt in one section. This is applicable for each version branch.
• Release workflow can use this CHANGES.txt as the release notes.
• Clear the CHANGES.txt as the content is saved in the release tag and start fresh.

I also noticed one thing the main now tracks both 11.0.0 and 10.4.0, we should create the branch_10_4 early (I'm not sure today when the branch_10_4 is created) and follow the same pattern the branch_10_4 will now have CHANGES.txt that only tracks upcoming 10.4.x.

[dweiss]

Having the same file with different content on branches won't work for cherry picking commits (backporting), unfortunately.

[prudhvigodithi]

Having the same file with different content on branches won't work for cherry picking commits (backporting), unfortunately.

If everyone appends to the end of the file and it's kept per version (cleared after each release), IMO conflicts should be minimal. We can also explore strategies like CHANGES.txt merge=union to .gitattributes.

[stefanvodita]

Not totally opposed to the idea of dividing CHANGES.txt across branches, but I've liked grepping for things in that one file in the past and being able to go far back in history.

[msokolov]

Yeah this is how I got the material for a talk I gave at Apache COC. It is a little sticky part of backporting though, would be nice if we could make it smoother

Sent from Proton Mail for Android.

-------- Original Message -------- On Friday, 11/28/25 at 16:24 Stefan Vodita @.***> wrote:

stefanvodita left a comment (apache/lucene#15421)

Not totally opposed to the idea of dividing CHANGES.txt across branches, but I've liked grepping for things in that one file in the past and being able to go far back in history.

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you are subscribed to this thread.Message ID: @.***>

[prudhvigodithi]

Not totally opposed to the idea of dividing CHANGES.txt across branches

Right, if we migrate CHANGES.txt per release model provided it gives more structured management, we can still grep for each tag and consolidate. I'm not sure how this works today https://lucene.apache.org/core/10_3_2/changes/Changes.html#older but in order not to break this we can have a workflow that generates a consolidated CHANGES.txt and park it in the repo.