docs(changelog): convert CHANGES.txt to Keep a Changelog

CHANGES.txt held twenty years of releases in a format that grew by accretion:
93 sections under six different heading shapes, 51 dates in five formats,
sixteen entry prefixes, and product sub-headings that partitioned a version
between core, the Eclipse plug-in and the IDEA plug-in. It is now CHANGELOG.md,
following Keep a Changelog 1.1.0.

The conversion is a format change. Every entry, sub-bullet, issue reference and
attribution is carried over word for word; the 751 GITHUB- and TESTNG-
references come out at 751, none lost and none invented, and the 93 sections
stay 93. What the file recorded about itself is kept too: a release that was
pulled keeps its own words and gains a [YANKED] marker, and the version that
[Unreleased] is heading for is named rather than dropped.

The sixteen prefixes fold into the six Keep a Changelog categories: New and
Added become Added, Update and Improved behavior become Changed, Fix a typo for
Fixed. A product sub-heading becomes a bold prefix on each of its entries, since
the format has no place for it. The breaking-change block, which three entries
refer to by name, stays a block, nested under Changed as a fourth-level heading.

Three things the file could not state are now stated:

- Dates. Sections stopped carrying one after 6.11, so 6.12 through 7.12.0 had
  none. They are reconstructed from tags, GitHub releases and Maven Central
  publication records. 4.6 was recorded as 2006/27/02, and month 27 does not
  exist; in an era spelling dates YYYY/MM/DD the day and month are swapped, so
  it reads 2006-02-27. The dates of 4.5 and 5.0 are chronologically impossible
  and are carried unchanged, because correcting them would be inventing.
- 7.5.1. It was released from the release_7.5 branch and never reached this
  file. Its section is reconstructed from the two commits between the 7.5 and
  7.5.1 tags, and sits where its date puts it, between 7.8.0 and 7.7.1.
- 5.0.1 was declared twice, in two sections separated by a rule. One version,
  one section.

Comparison links close the file for the 50 versions whose boundaries are both
tagged. 7.1.0 is not among them: it was published to Maven Central and never
tagged. Each link's base is the release the section's changes are measured
against, read from the release lineage rather than from the section above it. For
a release made from master that base is also a Git ancestor; it is not for 7.5.1,
whose branch forked before the 7.5 tag, and 7.5...7.5.1 is a divergent comparison
that still shows exactly the two commits that release shipped. Ordering by
section would have compared 7.8.0 against 7.5.1 and answered with 150 commits of
divergence instead of its 25.

The header does not claim Semantic Versioning. The version being prepared is a
minor one and its own Possible backward incompatible changes block breaks
org.testng, not only org.testng.internal, so the header says what the project
does instead: a minor release may carry a breaking change, and each is listed in
the section that ships it.

Around the file: .gitattributes carries the union merge strategy to the new
path, so two pull requests can still add a line each without conflicting.
AGENTS.md and the pull request template name the new file and its categories.
RELEASE_PROCESS.md gains the step that promotes [Unreleased] into a dated
section, which until now existed only in the habit of doing it. It runs after
tagging, not before, because the promotion adds commits and the tag has to point
at what was built -- which is the order 7.12.0 was actually released in. Its tag
command adopts a v prefix: the release stays 7.10.0, which is what
gradle.properties and Maven Central carry, and v7.10.0 is the name of the ref.
Releases up to 7.12.0 carry no prefix, so the first v tag compares against a bare
one and the rest follow. It also names the commit the publish workflow built rather than whatever local HEAD happens to
be: that workflow is dispatched by hand and checks out the branch head of the
moment, while the tagging happens half an hour later. The run is named
outright rather than taken as the most recent successful one, which a re-run, a
staged USER_MANAGED run or a second dispatch of the same version would each
satisfy, and its conclusion and the version its commit declares are both checked
before the tag is written.

Promoting the changelog now starts by diffing it against that commit. A pull
request merging while Central syncs leaves its entry under Unreleased with its
code outside the artifacts, and dating the section wholesale would file that work
under a version that never carried it while removing it from the one that will.

README.md now points at the changelog above its list of mailing list
announcements, which it keeps: the archive makes a single release hard to find,
which is why the list exists. The release step that updated README.md is now
about that list alone -- the four other things it named, a Maven example, a
Gradle example, download links and version badges, are none of them in that
file -- and it moves after the announcement, which is when the thread it links
to starts existing.

Author: juherr

.gitattributes

@@ -7,4 +7,4 @@
 *.yaml text
 *.yml text
 *.bat text eol=crlf
-/CHANGES.txt merge=union
+/CHANGELOG.md merge=union

.github/PULL_REQUEST_TEMPLATE.md

@@ -3,7 +3,7 @@ Fixes # .
 ### Did you remember to?
 
 - [ ] Add test case(s)
-- [ ] Update `CHANGES.txt`
+- [ ] Update `CHANGELOG.md`, under `## [Unreleased]`
 - [ ] Auto applied styling via `./gradlew autostyleApply`
 - [ ] Checked the wording of any javadoc, comments or docs you touched, via
       `./gradlew writingStyleCheckChanges` ([writing style](../docs/WRITING_STYLE.md))

AGENTS.md

@@ -248,15 +248,22 @@ From a fork, pull requests are cross-fork:
 gh pr create --repo testng-team/testng --base master --head <fork-owner>:<branch>
 ```
 
-Conventional Commits. Record user-visible changes in `CHANGES.txt`, newest first, under the current
-version heading.
-
-A change under `org.testng.internal` earns two `CHANGES.txt` entries: the `Changed:` line in prose,
-and a bullet under `Possible backward incompatible changes:` naming what stops compiling and what to
-use instead. The package is OSGi exported yet excluded from javadoc, which reads as a contradiction
-and invites deprecated bridges; the project does the opposite, breaking them and recording it, each
-entry naming the export and doing it anyway. Grep `CHANGES.txt` for `internal` before arguing
-about compatibility — the precedents are the argument.
+Conventional Commits. Record user-visible changes in `CHANGELOG.md`, newest first, under
+`## [Unreleased]`, in the `### Added`, `### Changed`, `### Deprecated`, `### Removed`, `### Fixed`
+or `### Security` subsection the change belongs to. The file follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+Put your entry under a subsection that is already there whenever you can. `.gitattributes` merges
+the changelog with the `union` strategy, which takes both sides of a concurrent edit rather than
+raising a conflict: two pull requests that each open the same missing subsection land two copies of
+that heading, silently, and nothing reads the file to catch it.
+
+A change under `org.testng.internal` earns two `CHANGELOG.md` entries: the `### Changed` line in
+prose, and a bullet under `#### Possible backward incompatible changes` naming what stops compiling
+and what to use instead. The package is OSGi exported yet excluded from javadoc, which reads as a
+contradiction and invites deprecated bridges; the project does the opposite, breaking them and
+recording it, each entry naming the export and doing it anyway. Grep `CHANGELOG.md` for `internal`
+before arguing about compatibility — the precedents are the argument.
 
 Split a pull request that mixes a large mechanical sweep with changes that need judgement. The two
 halves have different review costs: a tool's output — an OpenRewrite run, a formatter pass, a
@@ -313,7 +320,7 @@ edits that follow it, so a reviewer can tell which hunks a human actually judged
 - Running a documented command proves it executes, not that it does what the text claims. If the
   text promises an effect — filtering, failing, producing a value — measure that effect.
 - Report what you actually observed. If a run was flaky, say so and show both runs.
-- **What the characterization made fail is the minimum the fix has to cover.** A `CHANGES.txt`
+- **What the characterization made fail is the minimum the fix has to cover.** A `CHANGELOG.md`
   entry that has to disclaim part of it — "not covered until X migrates" — is the tell that the fix
   sits too high. Count the failing sites, then enumerate the callers of the shared primitive one
   level down. On GITHUB-2830 that primitive was `Utils.toString`, located by its already-failsafe

CHANGELOG.md

@@ -12,6 +12,11 @@ Documentation available at [TestNG's main web site](https://testng.org). Visit [
 > **Note for contributors:** Building TestNG from source requires JDK 21 or higher. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for details.
 
 ### Release Notes
+
+[CHANGELOG.md](CHANGELOG.md) covers every release, back to 0.2. The announcements below carry each
+release as it was sent to the [testng-users](https://groups.google.com/g/testng-users) mailing list,
+where a single release is otherwise hard to find.
+
 * [7.12.0](https://groups.google.com/g/testng-users/c/KLK7I7jagTQ)
 * [7.11.0](https://groups.google.com/g/testng-users/c/2z_tdavjZbA)
 * [7.10.0](https://groups.google.com/g/testng-users/c/6DmFaKUjIxY)

CHANGES.txt

@@ -63,18 +63,20 @@ TestNG uses GitHub Actions to automate the release process. The workflow:
                     │                           │
                     └───────────┬───────────────┘
                                 ▼
-                    ┌───────────────────────┐
-                    │ Artifacts on Maven    │
-                    │ Central (~30 minutes) │
-                    └───────────────────────┘
+                    ┌─────────────────────────┐
+                    │ Artifacts on Maven      │
+                    │ Central (~30 minutes)   │
+                    └─────────────────────────┘
                                 │
                                 ▼
-                    ┌───────────────────────┐
-                    │ Post-Release Tasks    │
-                    │ - Create Git tag      │
-                    │ - Send announcement   │
-                    │ - Update README       │
-                    └───────────────────────┘
+                    ┌─────────────────────────┐
+                    │ Post-Release Tasks      │
+                    │ - Create Git tag        │
+                    │ - Promote changelog     │
+                    │ - Create GitHub release │
+                    │ - Send announcement     │
+                    │ - Update README + docs  │
+                    └─────────────────────────┘
 ```
 
 ## Prerequisites
@@ -102,6 +104,10 @@ The following secrets must be configured in GitHub repository settings. The GitH
 
 ## Release Workflow
 
+Releases are made from `master`, and only from `master`. The branches that carry a release tag
+further back, `release_7.5` above all, are history rather than a supported path: they explain how a
+tag such as 7.5.1 came about, and nothing is published from them today.
+
 ### Option 1: Automatic Release (Recommended)
 
 This is the simplest approach - artifacts are automatically published to Maven Central without manual intervention.
@@ -113,7 +119,7 @@ This is the simplest approach - artifacts are automatically published to Maven C
 3. Click **"Run workflow"** button
 4. Select:
 
-   - **Branch**: `master` (or your release branch)
+   - **Branch**: `master`
    - **Publishing type**: `AUTOMATIC`
 
 5. Click **"Run workflow"**.
@@ -173,7 +179,7 @@ This approach uploads artifacts to Central Portal but waits for you to manually
 3. Click **"Run workflow"** button
 4. Select:
 
-   - **Branch**: `master` (or your release branch)
+   - **Branch**: `master`
    - **Publishing type**: `USER_MANAGED`
 
 5. Click **"Run workflow"**
@@ -313,35 +319,163 @@ After artifacts are published to Maven Central, complete these tasks:
 
 ### 1. Create Git Tag
 
-Every release must be tagged in Git.
+Every release must be tagged in Git, and tagging comes first: the next step adds commits, and the
+tag has to point at the commit the artifacts were built from.
+
+That commit is not always your local `HEAD`. `Publish to Maven Central` is a `workflow_dispatch`,
+and its checkout takes the head of the branch it was dispatched on, at the moment it was dispatched
+— while you reach this step half an hour later, once Central has synced, on a branch that may have
+moved. Read the commit off the run instead of assuming it:
+
+Name the run outright. Picking the newest successful one would be a guess: a re-run, a
+`USER_MANAGED` run that staged but was never published, and a second dispatch of the same version
+are all successful runs, and all of them build a commit that declares this version.
 
 ```bash
-# Get the version number from the release
 VERSION="7.10.0"  # Replace with actual version
 
-# Create and push the tag
-git tag -a v${VERSION} -m "Release ${VERSION}"
-git push origin v${VERSION}
+# Find the run you dispatched and watched above; its id is also the last path
+# segment of its URL, .../actions/runs/<id>
+gh run list --repo testng-team/testng --workflow "Publish to Maven Central" --limit 5 \
+  --json databaseId,headSha,conclusion,createdAt
+
+RUN_ID="21236984900"  # Replace with that run's id
+```
+
+Two guards before the tag is written. The first is the run, the second the commit, and neither is
+implied by the other:
+
+```bash
+gh run view "${RUN_ID}" --repo testng-team/testng --json conclusion --jq .conclusion \
+  | grep -qx success || { echo "Run ${RUN_ID} did not succeed"; exit 1; }
+
+RELEASE_COMMIT=$(gh run view "${RUN_ID}" --repo testng-team/testng --json headSha --jq .headSha)
+
+git show "${RELEASE_COMMIT}:gradle.properties" | grep -qx "testng.version=${VERSION}" \
+  || { echo "Run ${RUN_ID} built $(git show "${RELEASE_COMMIT}:gradle.properties" \
+       | grep '^testng.version='), not ${VERSION}"; exit 1; }
+
+git log -1 --oneline "${RELEASE_COMMIT}"
+git tag -a "v${VERSION}" "${RELEASE_COMMIT}" -m "TestNG ${VERSION}"
+git push origin "v${VERSION}"
+```
+
+**Note**: The tag is the version with a `v` in front, `v7.10.0`. The `v` belongs to the tag name and
+not to the version: the release is `7.10.0`, which is what `gradle.properties` and Maven Central
+carry. Prefixing marks a ref as a version at a glance, keeps release tags apart from every other
+ref, and is what the surrounding tooling expects — `npm version`, GoReleaser and Go modules all
+assume it, and the Semantic Versioning FAQ names it as the usual way to write a version tag.
+
+Releases up to and including `7.12.0` are tagged without the prefix, so the first `v` tag compares
+against a bare one. Only that one link is mixed; the rest follow.
+
+### 2. Promote the Changelog
+
+`CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), so releasing turns
+the section contributors have been filling in into a dated one, and opens a fresh one for the
+version that comes next.
+
+All of it happens on `master`, in a working copy, in one commit. The example below releases
+`7.10.0` and opens `7.11.0`.
+
+```bash
+git checkout master
+git pull origin master
+
+# Still holding RELEASE_COMMIT from step 1. Anything the changelog gained since that
+# commit is not in the release.
+git diff "${RELEASE_COMMIT}" HEAD -- CHANGELOG.md
+```
+
+An empty diff means the whole `## [Unreleased]` section is what shipped, and the steps below apply
+to it as written. A non-empty one means a pull request merged while Central was syncing: its entries
+are under `## [Unreleased]` but its code is not in the artifacts. Dating the section wholesale would
+file that work under a version that never carried it, and remove it from the version that will —
+wrong in both directions, and invisible afterwards. Leave those entries under the new
+`## [Unreleased]` you open in step 2.1, and date only the rest.
+
+#### 2.1 Date the section being released
+
+At the top of `CHANGELOG.md`, turn this:
+
+```markdown
+## [Unreleased]
+
+Next release: 7.10.0.
+
+### Added
+```
+
+into this, using the date the artifacts reached Maven Central:
+
+```markdown
+## [Unreleased]
+
+Next release: 7.11.0.
+
+## [7.10.0] - 2024-04-07
+
+### Added
+```
+
+The `### Added`, `### Changed` and other subsections stay where they are: they describe the release
+you just dated. The new `## [Unreleased]` starts empty, with only its `Next release:` line.
+
+A release that had to be pulled keeps its section and gains a `[YANKED]` marker in the heading,
+with the reason on the line underneath:
+
+```markdown
+## [7.10.0] - 2024-04-07 [YANKED]
+
+Bad release: wrong internal version.
+```
+
+#### 2.2 Update the link definitions
+
+At the foot of `CHANGELOG.md`, point `[Unreleased]` at the tag you just pushed and add a line for
+the release itself. The base is the release this one follows in the commit graph, which for a
+release made from `master` is the one before it there:
+
+```markdown
+[Unreleased]: https://github.com/testng-team/testng/compare/v7.10.0...HEAD
+[7.10.0]: https://github.com/testng-team/testng/compare/7.9.0...v7.10.0
 ```
 
-**Note**: The tag should point to the exact commit that was released.
+It is not the section above it in the file. Sections are ordered by release date, while a comparison
+link describes a Git delta, and the two orders part company for the maintenance releases already in
+the file: 7.5.1 was cut from a branch and shipped after 7.7.1, so its section sits between 7.8.0 and
+7.7.1 while its changes belong to the 7.5 line. That is why `[7.8.0]` compares against 7.7.1 rather
+than the section above it — taking 7.5.1 there would answer with 150 commits of divergence instead
+of the 25 that release delivered. Since releases now come from `master` only, a new entry cannot
+land in that position.
+
+#### 2.3 Bump the version
+
+In `gradle.properties`, set `testng.version` to the version you named in `Next release:`:
+
+```properties
+testng.version=7.11.0
+```
 
-### 2. Create GitHub Release
+#### 2.4 Commit and push
+
+```bash
+git add CHANGELOG.md gradle.properties
+git commit -m "Bumping version for next release"
+git push origin master
+```
+
+### 3. Create GitHub Release
 
 1. Go to https://github.com/testng-team/testng/releases
 2. Click **"Draft a new release"**
 3. Select the tag you just created (`v7.10.0`)
 4. Set release title: `TestNG 7.10.0`
-5. Add release notes:
-
-   - Highlight major features
-   - List bug fixes
-   - Link to issues/PRs
-   - Credit contributors
-
+5. Add release notes, taken from the section you just dated in `CHANGELOG.md`. That file is the
+   source; the release page repeats it rather than restating it in other words.
 6. Click **"Publish release"**
 
-### 3. Send Release Announcement
+### 4. Send Release Announcement
 
 Send an email to the TestNG users mailing list:
 
@@ -382,24 +516,22 @@ Thanks to all contributors who made this release possible!
 [Your Name]
 ```
 
-### 4. Update README.md
+### 5. Link the Announcement from README.md
 
-Update the version badge and links in README.md:
+The `### Release Notes` list in `README.md` points at one mailing list thread per release, because a
+single release is hard to find in the archive otherwise. Add the thread you just sent, at the top:
 
-```bash
-# Edit README.md
-# Update version numbers in:
-# - Maven dependency example
-# - Gradle dependency example
-# - Download links
-# - Version badges
+```markdown
+* [7.10.0](https://groups.google.com/g/testng-users/c/<thread-id>)
+```
 
+```bash
 git add README.md
-git commit -m "Update README for 7.10.0 release"
+git commit -m "Add 7.10.0 release notes link"
 git push origin master
 ```
 
-### 5. Update Documentation
+### 6. Update Documentation
 
 If there are documentation changes:
 

README.md

@@ -325,9 +325,11 @@ without checking.
 - **Terminology replacements.** See step 2 of
   [Adding or changing a rule](#adding-or-changing-a-rule). The measurement kills it.
 
-- **Checking `CHANGES.txt`.** It holds twenty years of contributor names and issue numbers. On its
-  own it produced more than nine tenths of every finding in the repository. So `.vale.ini` covers
-  `*.md` and `*.java` only.
+- **Checking `CHANGELOG.md`.** It holds twenty years of contributor names and issue numbers. On its
+  own it produced more than nine tenths of every finding in the repository. `.vale.ini` covers
+  `*.md` and `*.java`, so the changelog gets a `[**/CHANGELOG.md]` section of its own with an
+  empty `BasedOnStyles`, which switches every style off for that one file and no other. The
+  `**/` matters: the Gradle task passes absolute paths, which a bare `CHANGELOG.md` misses.
 
 - **Keeping the rules on this page.** Tools do not reliably follow links, so the rules have to sit
   in the file the tool already reads. That is why they are in `AGENTS.md`.