This is an automated email from the ASF dual-hosted git repository. dsmiley pushed a commit to branch branch_10x in repository https://gitbox.apache.org/repos/asf/solr.git
commit e97632af65a44d8721fad0f49f40094a2523d3ad 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]> (cherry picked from commit 232690c9dd8c9a03bd552923c69d3fafbeade0f8) --- dev-docs/changelog.adoc | 32 ++++++++-------------------- dev-tools/scripts/validate-changelog-yaml.py | 11 +++++++++- gradle/changelog.gradle | 30 +++++++++++++++++++++++--- 3 files changed, 46 insertions(+), 27 deletions(-) diff --git a/dev-docs/changelog.adoc b/dev-docs/changelog.adoc index a9f671c544a..d8b767c81d7 100644 --- a/dev-docs/changelog.adoc +++ b/dev-docs/changelog.adoc @@ -113,25 +113,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: @@ -140,9 +126,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: @@ -164,7 +150,7 @@ The `logchangeRelease` and `logchangeGenerate` tasks are used by ReleaseWizard. These are integrated in the Release Wizard via `dev-tools/scripts/logchange.py`, which also handles RC2+ scenarios — see section 5.4. -=== 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. @@ -195,7 +181,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 diff --git a/dev-tools/scripts/validate-changelog-yaml.py b/dev-tools/scripts/validate-changelog-yaml.py index 0a41586c781..fa7369ebd4c 100644 --- a/dev-tools/scripts/validate-changelog-yaml.py +++ b/dev-tools/scripts/validate-changelog-yaml.py @@ -30,6 +30,7 @@ Checks: - Contains required 'type' field (one of: added, changed, fixed, deprecated, removed, dependency_update, security, other) - Contains required 'authors' field with at least one author - Each author has a 'name' field (non-empty string) +- Comment block is removed """ import sys @@ -40,10 +41,12 @@ import yaml def validate_changelog_yaml(file_path): """Validate a changelog YAML file. Returns True if valid.""" valid_types = ['added', 'changed', 'fixed', 'deprecated', 'removed', 'dependency_update', 'security', 'other'] + 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): @@ -86,6 +89,12 @@ def validate_changelog_yaml(file_path): print(f"::error file={file_path}::Author {i} 'name' must be a non-empty string") 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/gradle/changelog.gradle b/gradle/changelog.gradle index 661c8cfb54f..69d2d6e87f7 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, 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 it" + println "Generated file: ${fileName} -- open and edit before committing" + println "Read dev-docs/changelog.adoc if you don't contribute here often." } }
