From 93bcfc2bfeecb4c044c1570053959427e52eee20 Mon Sep 17 00:00:00 2001
From: Wei Lee <weilee.rx@gmail.com>
Date: Wed, 27 Nov 2024 15:48:20 +0800
Subject: [PATCH] docs(newsfragment): add template for significant
 newsfragments (#44378)

* docs(newsfragment): add template for significant newsfragments

Closes: #44374

* docs(contributing-docs): add sigificant file template description

* ci(github-actions): add script to check the news fragment content
---
 .github/workflows/news-fragment.yml           | 25 ++++++++++++++++++-
 .../16_contribution_workflow.rst              |  7 +++++-
 newsfragments/template.significant.rst        | 19 ++++++++++++++
 3 files changed, 49 insertions(+), 2 deletions(-)
 create mode 100644 newsfragments/template.significant.rst

diff --git a/.github/workflows/news-fragment.yml b/.github/workflows/news-fragment.yml
index bf1bd6ce27b2b..4bcf95e2bba88 100644
--- a/.github/workflows/news-fragment.yml
+++ b/.github/workflows/news-fragment.yml
@@ -36,7 +36,7 @@ jobs:
           # needs a non-shallow clone.
           fetch-depth: 0
 
-      - name: Check news fragment
+      - name: Check news fragment existence
         run: >
           python -m pip install --upgrade uv &&
           uv tool run towncrier check
@@ -52,3 +52,26 @@ jobs:
           &&
           false
           ; }
+
+      - name: Check news fragment contains change types
+        run: >
+          change_types=(
+            'DAG changes'
+            'Config changes'
+            'API changes'
+            'CLI changes'
+            'Behaviour changes'
+            'Plugin changes'
+            'Dependency change'
+          )
+          news_fragment_content=`git diff origin/${{ github.base_ref }} newsfragments/*.significant.rst`
+
+          for type in "${change_types[@]}"; do
+            if [[ $news_fragment_content != *"$type"* ]]; then
+              printf "\033[1;33mMissing change type '$type' in significant newsfragment for PR labeled with
+              'airflow3.0:breaking'.\nCheck
+              https://github.com/apache/airflow/blob/main/contributing-docs/16_contribution_workflow.rst
+              for guidance.\033[m\n"
+              exit 1
+            fi
+          done
diff --git a/contributing-docs/16_contribution_workflow.rst b/contributing-docs/16_contribution_workflow.rst
index 8c941f8afc7a4..1c933ebe9e780 100644
--- a/contributing-docs/16_contribution_workflow.rst
+++ b/contributing-docs/16_contribution_workflow.rst
@@ -196,7 +196,12 @@ Step 4: Prepare PR
      and place in either `newsfragments <https://github.com/apache/airflow/blob/main/newsfragments>`__ for core newsfragments,
      or `chart/newsfragments <https://github.com/apache/airflow/blob/main/chart/newsfragments>`__ for helm chart newsfragments.
 
-     In general newsfragments must be one line.  For newsfragment type ``significant``, you may include summary and body separated by a blank line, similar to ``git`` commit messages.
+     In general newsfragments must be one line.  For newsfragment type ``significant``,
+     you should follow the template in ``newsfragments/template.significant.rst`` to include summary, body, change type and migrations rules needed.
+     This can also be done by the following command.
+
+.. code-block:: bash
+     uv tool run towncrier create --dir . --config newsfragments/config.toml --content "`cat newsfragments/template.significant.rst`"
 
 2. Rebase your fork, squash commits, and resolve all conflicts. See `How to rebase PR <#how-to-rebase-pr>`_
    if you need help with rebasing your change. Remember to rebase often if your PR takes a lot of time to
diff --git a/newsfragments/template.significant.rst b/newsfragments/template.significant.rst
new file mode 100644
index 0000000000000..8431b2469c944
--- /dev/null
+++ b/newsfragments/template.significant.rst
@@ -0,0 +1,19 @@
+.. Write a short and imperative summary of this changes
+
+.. Provide additional contextual information
+
+.. Check the type of change that applies to this change
+
+* Types of change
+
+  * [ ] DAG changes
+  * [ ] Config changes
+  * [ ] API changes
+  * [ ] CLI changes
+  * [ ] Behaviour changes
+  * [ ] Plugin changes
+  * [ ] Dependency change
+
+.. List the migration rules needed for this change (see https://github.com/apache/airflow/issues/41641)
+
+* Migrations rules needed