This is an automated email from the ASF dual-hosted git repository.
dsmiley pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/main by this push:
new 232690c9dd8 changelog: move entry advise into template (#4111)
232690c9dd8 is described below
commit 232690c9dd8c9a03bd552923c69d3fafbeade0f8
Author: David Smiley <[email protected]>
AuthorDate: Fri Feb 20 22:55:49 2026 -0500
changelog: move entry advise into template (#4111)
And improve/clarify advise.
Remove "security" as a type, which is orthogonal to the existing types.
Co-authored-by: Jan Høydahl <[email protected]>
---
.github/scripts/validate-changelog-yaml.py | 11 +++++++++-
dev-docs/changelog.adoc | 34 +++++++++---------------------
gradle/changelog.gradle | 28 ++++++++++++++++++++++--
3 files changed, 46 insertions(+), 27 deletions(-)
diff --git a/.github/scripts/validate-changelog-yaml.py
b/.github/scripts/validate-changelog-yaml.py
index 5503872cf6b..5664a37c404 100644
--- a/.github/scripts/validate-changelog-yaml.py
+++ b/.github/scripts/validate-changelog-yaml.py
@@ -30,6 +30,7 @@ Checks:
- 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']}")
diff --git a/dev-docs/changelog.adoc b/dev-docs/changelog.adoc
index 6e0f2973230..ee503457a9e 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 00770b0688d..aa9c32a13a3 100644
--- a/gradle/changelog.gradle
+++ b/gradle/changelog.gradle
@@ -54,15 +54,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, 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. 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
+# `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.
+
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 and edit before committing"
+ println "Read dev-docs/changelog.adoc if you don't contribute here often."
}
}
