From 064662b16f67b2f8ce9e10fc61b033a864943a68 Mon Sep 17 00:00:00 2001 From: David Smiley Date: Fri, 6 Feb 2026 14:21:06 -0500 Subject: [PATCH 1/3] changelog: move entry advise into template Move entry advise from the adoc into the entry template. Improve / clarify the advise. Drop `security` type, which is orthogonal. --- dev-docs/changelog.adoc | 34 ++++++++++------------------------ gradle/changelog.gradle | 28 ++++++++++++++++++++++++++-- 2 files changed, 36 insertions(+), 26 deletions(-) diff --git a/dev-docs/changelog.adoc b/dev-docs/changelog.adoc index 6e0f2973230e..ee503457a9ed 100644 --- a/dev-docs/changelog.adoc +++ b/dev-docs/changelog.adoc @@ -78,25 +78,11 @@ user.githubid=johngithub user.asfid=johnapache ---- -TIP: Aliases for `writeChangelog` task are `changelog` and `newChangelog`. - -== 4. Writing Good Entries - -* **Audience** is end-users and administrators, not committers. -* If the change is super minor, like a typo, don't bother adding a yaml file -* Keep the entry short and focused on the user impact. -* Choose the correct *type*: -** `added` for new features -** `changed` for improvements to existing code -** `fixed` for bug fixes -** `deprecated` for deprecated features -** `removed` for code removed in major releases -** `dependency_update` for updates to dependencies -** `security` for security-related changes -** `other` for anything else, like the build or documentation -* Reference issues as `SOLR-12345` or GitHub `PR#123`. - -== 5. Changelog Validation in Pull Requests +The changelog has comments to help you fill it out. Remove them after filling out the form. + +TIP: Aliases for the `writeChangelog` task are `changelog` and `newChangelog`. + +== 4. Changelog Validation in Pull Requests The `validate-changelog` GitHub workflow automatically checks that: @@ -105,9 +91,9 @@ The `validate-changelog` GitHub workflow automatically checks that: If your change does not require a changelog entry, it is still possible to merge the PR. -== 6. For release managers +== 5. For release managers -=== 6.1 Gradle tasks for logchange +=== 5.1 Gradle tasks for logchange The logchange gradle plugin offers some tasks, here are the two most important: @@ -129,7 +115,7 @@ The `logchangeRelease` and `logchangeGenerate` tasks are used by ReleaseWizard. These are integrated in the Release Wizard. -=== 6.2 Migration tool +=== 5.2 Migration tool There is a migration tool in `dev-tools/scripts/changes2logchange.py` for one-time use during the transition. It will bulk convert the entire `solr/CHANGES.txt` file to files in the `changelog/` folder and versioned sub folders. @@ -160,7 +146,7 @@ links: url: https://issues.apache.org/jira/browse/SOLR-17960 ---- -=== 6.3 Changelog validation tool +=== 5.3 Changelog validation tool There is a tool `dev-tools/scripts/validateChangelogs.py` that will do a cross-branch validation of changelog folders. It takes no arguments and @@ -245,7 +231,7 @@ Example report output (Json or Markdown): } ---- -== 7. Further Reading +== 6. Further Reading * https://github.com/logchange/logchange[Logchange web page] * https://keepachangelog.com/en/1.1.0/[keepachangelog.com website] diff --git a/gradle/changelog.gradle b/gradle/changelog.gradle index 661c8cfb54fb..5586ed36a025 100644 --- a/gradle/changelog.gradle +++ b/gradle/changelog.gradle @@ -50,15 +50,39 @@ task writeChangelog { def fileName = "changelog/unreleased/${sanitizedBranchName}.yml" def file = new File(fileName) file.parentFile.mkdirs() - file.text = """# See https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc + file.text = """# (DELETE ALL COMMENTS UP HERE AFTER FILLING THIS IN + +# See https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc + +# If the change is minor (typos, small improvements), don't bother adding an entry. + +# title: +# * The audience is end-users and administrators, not committers. +# * Be short and focused on the user impact, nevertheless multiple sentences is fine! +# * For technical/geeky details, prefer the commit message instead of changelog + +# type: +# `added` for new features/improvements, opt-in by the user typically documented in the ref guide +# `changed` for improvements; not opt-in +# `fixed` for improvements that are deemed to have fixed buggy behavior +# `deprecated` for marking things deprecated +# `removed` for code removed +# `dependency_update` for updates to dependencies +# `other` for anything else, like large/significant refactorings, build changes, +# test infrastructure, or documentation. +# Most such changes are too small/minor to bother with a changelog entry. + +# Reference issues as `SOLR-12345` or GitHub `PR#123`. + title: ${title} -type: other # added, changed, fixed, deprecated, removed, dependency_update, security, other +type: authors: - name: ${configuredName}${nick}${asfIdUrl} ${jiraLinks} """ println "Generated file: ${fileName} -- open it" + println "Read dev-docs/changelog.adoc if you don't contribute here often." } } From b54e37c8936be9981a28639b389b3d7007fc4e28 Mon Sep 17 00:00:00 2001 From: David Smiley Date: Wed, 18 Feb 2026 23:16:32 -0500 Subject: [PATCH 2/3] Improve clarity --- gradle/changelog.gradle | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/gradle/changelog.gradle b/gradle/changelog.gradle index 5586ed36a025..ad52de2066ed 100644 --- a/gradle/changelog.gradle +++ b/gradle/changelog.gradle @@ -54,12 +54,14 @@ task writeChangelog { # See https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc -# If the change is minor (typos, small improvements), don't bother adding an entry. +# If the change is minor, don't bother adding a changelog entry. +# For `other` type entries, the threshold to bother with a changelog entry should be even higher. # title: # * The audience is end-users and administrators, not committers. -# * Be short and focused on the user impact, nevertheless multiple sentences is fine! -# * For technical/geeky details, prefer the commit message instead of changelog +# * Be short and focused on the user impact. Multiple sentences is fine! +# * For technical/geeky details, prefer the commit message instead of changelog. +# * Reference JIRA issues like `SOLR-12345`, or if no JIRA but have a GitHub PR then `PR#12345`. # type: # `added` for new features/improvements, opt-in by the user typically documented in the ref guide @@ -72,8 +74,6 @@ task writeChangelog { # test infrastructure, or documentation. # Most such changes are too small/minor to bother with a changelog entry. -# Reference issues as `SOLR-12345` or GitHub `PR#123`. - title: ${title} type: authors: From 182f4294e6b495598f2d52e8f3e9e8c1f5416775 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Thu, 19 Feb 2026 23:06:56 +0100 Subject: [PATCH 3/3] Update validate-changelog-yaml.py to fail if comments are left in --- .github/scripts/validate-changelog-yaml.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/scripts/validate-changelog-yaml.py b/.github/scripts/validate-changelog-yaml.py index 5503872cf6b6..5664a37c404c 100644 --- a/.github/scripts/validate-changelog-yaml.py +++ b/.github/scripts/validate-changelog-yaml.py @@ -30,6 +30,7 @@ - Each author has a 'name' field (non-empty string) - Contains either 'links' or 'issues' field (or both) - If 'issues' is present, it must be an integer not exceeding 17000 +- Comment block is removed """ import sys @@ -41,10 +42,12 @@ def validate_changelog_yaml(file_path): valid_types = ['added', 'changed', 'fixed', 'deprecated', 'removed', 'dependency_update', 'security', 'other'] valid_keys = ['title', 'type', 'issues', 'links', 'important_notes', 'modules', 'authors'] deprecated_keys = ['merge_requests', 'configurations'] + not_allowed_text = ['DELETE ALL COMMENTS UP HERE', 'Most such changes are too small'] try: with open(file_path, 'r', encoding='utf-8') as f: - data = yaml.safe_load(f) + raw_content = f.read() + data = yaml.safe_load(raw_content) # Check if file contains a mapping (dictionary) if not isinstance(data, dict): @@ -120,6 +123,12 @@ def validate_changelog_yaml(file_path): print(f"::error file={file_path}::Field 'issues' value {data['issues']} points to a non-existing github PR. Did you intend to reference a JIRA issue, please use 'links'.") return False + # Validate that comments are removed + for not_allowed in not_allowed_text: + if not_allowed in raw_content: + print(f"::error file={file_path}::File still contains commented template text. Please remove the comment block at the top of the file.") + return False + # All validations passed print(f"✓ {file_path} is valid") print(f" Title: {data['title']}")