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']}") 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 00770b0688db..aa9c32a13a39 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." } }