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 <janhoy@apache.org>

Author: dsmiley

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

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]

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."
   }
 }