Added CHANGELOG.rst file and changed to fragments based change log

Signed-off-by: Andreas Maier <[email protected]>

.github/workflows/test.yml

@@ -257,6 +257,11 @@ jobs:
         PACKAGE_LEVEL: ${{ matrix.package_level }}
       run: |
         make check_reqs
+    - name: Run check_frag
+      env:
+        PACKAGE_LEVEL: ${{ matrix.package_level }}
+      run: |
+        make check_frag
     - name: Run check
       env:
         PACKAGE_LEVEL: ${{ matrix.package_level }}

.gitignore

@@ -23,6 +23,7 @@ tmp_*
 /tests/output/
 /AUTHORS
 /ChangeLog
+/changelogs/.plugin-cache.yaml
 /build/
 /gh-pages/
 /docs_local

Makefile

@@ -125,9 +125,9 @@ ifeq ($(python_m_n_version),3.5)
   check_reqs_packages := ansible pip_check_reqs pytest coverage coveralls flake8
 else
 ifeq ($(python_m_n_version),3.6)
-  check_reqs_packages := ansible pip_check_reqs pytest coverage coveralls flake8 sphinx ansible_doc_extractor
+  check_reqs_packages := ansible pip_check_reqs pytest coverage coveralls flake8 sphinx ansible_doc_extractor antsibull_changelog
 else
-  check_reqs_packages := ansible pip_check_reqs pytest coverage coveralls flake8 sphinx ansible_doc_extractor ansible_test pylint
+  check_reqs_packages := ansible pip_check_reqs pytest coverage coveralls flake8 sphinx ansible_doc_extractor antsibull_changelog ansible_test pylint
 endif
 endif
 endif
@@ -195,6 +195,7 @@ help:
 	@echo '  sanity     - Run Ansible sanity tests (includes pep8, pylint, validate-modules)'
 	@echo '  safety     - Run safety on sources'
 	@echo '  check_reqs - Perform missing dependency checks'
+	@echo '  check_frag - Run antsibull-changelog lint on change log fragments'
 	@echo '  docs       - Build the documentation for all enabled (docs/source/conf.py) versions in: $(doc_build_dir) using remote repo'
 	@echo '  docslocal  - Build the documentation from local repo contents in: $(doc_build_local_dir)'
 	@echo '  linkcheck  - Check links in documentation'
@@ -226,7 +227,7 @@ help:
 	@echo '  ansible-playbook playbooks/....'
 
 .PHONY: all
-all: install develop dist safety check sanity check_reqs docs docslocal linkcheck test end2end_mocked
+all: install develop dist safety check sanity check_reqs check_frag docs docslocal linkcheck test end2end_mocked
 	@echo '$@ done.'
 
 .PHONY: install
@@ -309,6 +310,16 @@ endif
 endif
 	@echo "Makefile: $@ done."
 
+.PHONY: check_frag
+check_frag: _check_version develop_$(pymn).done
+ifneq ($(doc_build),true)
+	@echo "Makefile: Warning: Skipping the checking of changelog fragments on Python $(python_m_n_version)"
+else
+	@echo "Makefile: Checking changelog fragments"
+	antsibull-changelog lint -vv
+endif
+	@echo "Makefile: $@ done."
+
 .PHONY:	end2end
 end2end: _check_version develop_$(pymn).done
 	bash -c 'PYTHONWARNINGS=default ANSIBLE_LIBRARY=$(module_py_dir) PYTHONPATH=. TESTEND2END_LOAD=true pytest -v $(pytest_opts) $(test_dir)/end2end'
@@ -425,12 +436,14 @@ $(doc_build_dir)/index.html: $(doc_rst_files) $(doc_source_dir)/conf.py
 ifneq ($(doc_build),true)
 	@echo "makefile: Warning: Skipping docs build on Python $(python_m_n_version)"
 else
+	antsibull-changelog generate --reload-plugins -vv
 	sphinx-versioning -l $(doc_source_dir)/conf.py build $(doc_source_dir) $(doc_build_dir)
 	touch $(doc_build_dir)/.nojekyll
 endif
 
 .PHONY: docslocal
 docslocal: _check_version develop_$(pymn).done $(doc_rst_files) $(doc_source_dir)/conf.py
 	rm -rf $(doc_build_local_dir)
+	antsibull-changelog generate --reload-plugins -vv
 	sphinx-build -b html $(sphinx_opts) $(doc_source_dir) $(doc_build_local_dir)
 #	open $(doc_build_local_dir)/index.html

changelogs/config.yaml

@@ -0,0 +1,32 @@
+changelog_filename_template: ../CHANGELOG.rst
+changelog_filename_version_depth: 0
+changes_file: changelog.yaml
+changes_format: combined
+ignore_other_fragment_extensions: true
+keep_fragments: false
+mention_ancestor: true
+new_plugins_after_name: removed_features
+notesdir: fragments
+prelude_section_name: release_summary
+prelude_section_title: Release Summary
+sanitize_changelog: true
+sections:
+- - major_changes
+  - Major Changes
+- - minor_changes
+  - Minor Changes
+- - breaking_changes
+  - Breaking Changes
+- - deprecated_features
+  - Deprecated Features
+- - removed_features
+  - Removed Features (previously deprecated)
+- - security_fixes
+  - Security Fixes
+- - bugfixes
+  - Bugfixes
+- - known_issues
+  - Known Issues
+title: IBM Z HMC Collection
+trivial_section_name: trivial
+use_fqcn: true

changelogs/fragments/731-changelog_rst.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+  - docs - Added CHANGELOG.rst file and changed to fragments based change log (issue 731).

dev-requirements.txt

@@ -59,6 +59,13 @@ pathspec>=0.8.0
 rstcheck>=3.3.1,<3.5; python_version >= '3.5' and python_version <= '3.6'  # ansible <= 2.10 (on minimum package levels)
 rstcheck>=3.3.1,<4.0; python_version >= '3.7' and python_version <= '3.9'  # ansible >= 4
 
+# antsibull-changelog - invoked only on Python>=3.6
+# antsibull-changelog 0.18.0 removed support for Python 3.6-3.8
+antsibull-changelog>=0.17.0; python_version >= '3.6'
+semantic-version>=2.10.0; python_version >= '3.6'
+# antsibull-changelog also uses rstcheck on Python>=3.8
+rstcheck-core>=1.0.3; python_version >= '3.8'
+
 # Safety CI by pyup.io
 # Safety is run only on Python >=3.6
 safety>=2.2.0; python_version >= '3.6'

docs/source/development.rst

@@ -317,23 +317,50 @@ local clone of the zhmc-ansible-modules Git repo.
 
         version: M.N.U
 
-4.  Edit the change log:
+4.  Update the change log:
 
-    .. code-block:: sh
+    * Add the new version and the changelog fragments to the changelog file:
 
-        vi docs/source/release_notes.rst
+      .. code-block:: sh
+
+          antsibull-changelog release -vv
+
+      This removes the changelog fragment files.
+
+    * Edit the changelog file:
+
+      .. code-block:: sh
+
+          vi changelogs/changelog.yaml
+
+      and add a ``release_summary`` item in the section for the version that is being
+      released, as follows:
+
+      .. code-block:: yaml
+
+          M.N.U:
+            changes:
+              minor_changes:
+              - . . .
+              - . . .
+              release_summary: Released on 2023-08-26.
+                Functional enhancements and bug fixes.
+                This version contains all fixes up to version M.N-1.x.
+            fragments:
+            - . . .
+            - . . .
+            release_date: '2023-08-26'
+
+      The date for "Released on" should be the same date as in ``release_date``.
+
+      The sentence "This version contains ..." is only needed if there have been
+      releases of fix versions on the prior minor version.
+
+    * Generate/update CHANGELOG.rst:
+
+      .. code-block:: sh
 
-    and make the following changes in the section of the version that is being
-    released:
-
-    * Finalize the version.
-    * Change the release date to today's date.
-    * Make sure that all changes are described.
-    * Make sure the items shown in the change log are relevant for and
-      understandable by users.
-    * In the "Known issues" list item, remove the link to the issue tracker and
-      add text for any known issues you want users to know about.
-    * Remove all empty list items.
+          make docslocal
 
 5.  Commit your changes and push the topic branch to the remote repo: