NO-JIRA: introduce changelog summary by release (#176)

**What this PR does / why we need it**:

Update the changelog builder with release summarization. 


**Which issue(s) this PR fixes** *(optional, use `fixes
#<issue_number>(, fixes #<issue_number>, ...)` format, where
issue_number might be a GitHub issue, or a Jira story*:
Fixes #

**Checklist**
- [ ] Subject and description added to both, commit and PR.
- [x] Relevant issues have been referenced.
- [x] This change includes docs. 
- [ ] This change includes unit tests.

## Tests

![Screenshot From 2025-04-28
13-45-11](https://github.com/user-attachments/assets/462730fe-88d4-4973-959f-a72d38c032f4)

Author: mtulio

.gitignore

@@ -8,4 +8,6 @@ build/
 
 # changelog is generated automaticaly by hack/generate-changelog.sh
 # available only in the rendered webpage (built by mkdocs).
+# See the make commands: 'build-changelog' and 'build-changelog-commmits'
 docs/CHANGELOG.md
+docs/CHANGELOG_commits.md

Makefile

@@ -102,6 +102,10 @@ clean:
 # .github/workflows/static-website.yml
 # docs/requirements.txt
 
+.PHONY: build-changelog-commits
+build-changelog-commits:
+	./hack/generate-changelog.sh "commits-only"
+
 .PHONY: build-changelog
 build-changelog:
 	./hack/generate-changelog.sh

docs/CHANGELOG_summary.md

@@ -0,0 +1,204 @@
+<!-- 
+
+File: CHANGELOG_summary.md
+Summary section generated manually by AI text summarization from a file CHANGELOG_commits.md.
+
+Steps to update the summary:
+- Generate the CHANGELOG_commits.md: make build-changelog-commits
+- Query the inference API by attaching the CHANGELOG_commits.md and instructions (below)
+- Update (manually) the file docs/CHANGELOG_summary.md (this file) in the section you want to summarize (last release, maybe?).
+- Generate the CHANGELOG.md: make build-changelog
+- Run the mkdocs locally: mkdocs serve
+- Check the reults on page: 127.0.0.1:8000/opct/CHANGELOG
+- Commit the changes (CHANGELOG_summary.md)
+
+Below are prompt details (copy/paste the following lines):
+---
+Instructions:
+You are a tech writer review expert and need to extract information from a changelog file (CHANGELOG_commits.md) of an open-source project.
+
+Extraction instruction:
+- Write a consolidated changelog summary from a markdown file containing commits by release.
+The summary must group the features by release, such as: enhancements, result review improvements, bug fixes, clean-up, others.
+- The result summary must aggregate releases by Y-stream, examples: v0.5.x, v0.6.x...
+- The result summary file must be a raw markdown file in a code block, without any additional context. A section in second-level ('##') with the name 'Release Summary', and each child section by release ('###').
+- The groups must be in bold name, example '**Enhancements**:', and each item must be in a bullet list. The first line must be blank to prevent markdown-to-HTML rendering issues.
+- Do not search for external content, only run a text summarization with files provided.
+- Do not add commit, PR, or task numbers.
+
+Example of the first lines of the result file (inside the code block):
+~~~
+## Release Summary
+
+### v0.6.x
+
+**Enhancements**:
+
+- Added checks for validating cluster install time and SLOs for valid install/platform (VCSP)
+- Introduced a controller to mutate unschedulable e2e pods
+
+**Bug Fixes**:
+
+- Disabled kube-burner to address long-running issues
+- Fixed matchExpressions to remove trailing commas
+
+**Clean Up**:
+
+- Renamed and improved commands and documentation for node setup and tainting
+- Improved documentation structure and changelog CD pipeline
+
+**Review Improvements**:
+
+- Reviewed and updated report, installation, and CLI documentation
+- Updated project owners and CI steps
+
+### v0.5.x
+
+**Enhancements**:
+
+- Added multi-arch build instructions and ARM64 support
+- Improved status command and increased verbosity for failure detection
+
+**Bug Fixes**:
+
+- Fixed Kubernetes service URL, conformance checks, and node/MCP checks
+- Fixed typos, cache expiration, and data handling in result archives
+
+...
+~~~
+
+Goal:
+Read the CHANGELOG_commits.md and generate the summary file CHANGELOG_summary.md as a result, following the instructions provided.
+-->
+
+<!-- Final Tips:
+- To prevent changing past releases, update only the release you are summarizing.
+- If you are improving the summarization, feel free to update the other sections. ;)
+-->
+
+
+## Release Summary
+
+### v0.6.x
+
+*Enhancements*:
+
+- Introduced checks to validate cluster install time and VCSP platform compatibility
+- Added controller to handle unschedulable e2e pods
+- Implemented automated check rule documentation generation
+- Enhanced archive cleanup processes for unused objects
+
+*Bug Fixes*:
+
+- Disabled kube-burner to resolve long-running test issues
+- Fixed matchExpressions syntax by removing trailing commas
+- Addressed security alerts through dependency updates
+
+*Clean Up*:
+
+- Renamed CLI commands for node tainting and dedicated node setup
+- Updated documentation structure and changelog pipeline
+- Streamlined CI workflows and label enforcement
+
+*Review Improvements*:
+
+- Created visual process diagrams for user guides
+- Updated SLO/rules documentation with automatic validation
+- Improved CLI reference and installation review guides
+
+### v0.5.x
+
+*Enhancements*:
+
+- Added ARM64 support and multi-arch build capabilities
+- Introduced batch report generation and manual e2e execution guides
+- Implemented disconnected registry mirror support
+- Enhanced status monitoring with configurable intervals
+
+*Bug Fixes*:
+
+- Fixed Kubernetes service URL and conformance check logic
+- Resolved node label/MCP upgrade validation issues
+- Addressed security vulnerabilities in dependencies
+- Improved error handling for missing optional metrics
+
+*Clean Up*:
+
+- Renamed project binaries and documentation references
+- Migrated to embedded file systems (EFS) from bindata
+- Updated CI pipelines with static analysis and linter jobs
+
+*Review Improvements*:
+
+- Created community standards documentation
+- Automated check rule documentation generation
+- Added upgrade execution mode documentation
+
+### v0.4.x
+
+*Enhancements*:
+
+- Added platformName field validation for external clusters
+- Introduced dedicated mode execution by default
+
+*Bug Fixes*:
+
+- Backported OCP 4.14 compatibility fixes
+- Addressed container security issues through UBI updates
+
+*Clean Up*:
+
+- Removed certification references from documentation
+- Improved RBAC configuration and namespace management
+
+### v0.3.x
+
+*Enhancements*:
+
+- Implemented upgrade execution mode
+- Added dev environment test limitation flag
+- Introduced automated changelog generation
+
+*Bug Fixes*:
+
+- Fixed plugin status counters and PSA label application
+- Addressed SCC creation conflicts
+
+*Review Improvements*:
+
+- Created documentation website with GitHub Pages
+- Added support matrix for OCP versions
+
+### v0.2.x
+
+*Enhancements*:
+
+- Implemented artifacts collector for test results
+- Added dedicated node execution mode
+
+*Bug Fixes*:
+
+- Fixed regression issues in plugin image
+- Addressed namespace conflicts in aggregator
+
+*Clean Up*:
+
+- Standardized plugin manifest naming conventions
+- Improved documentation structure and FAQ
+
+### v0.1.x
+
+*Enhancements*:
+
+- Initial release with core certification workflow
+- Added pre-checks for cluster stability and registry management
+
+*Bug Fixes*:
+
+- Resolved namespace conflicts and RBAC issues
+- Fixed status monitoring retry logic
+
+*Clean Up*:
+
+- Established release process documentation
+- Implemented code formatting and linting standards

hack/generate-changelog.sh

@@ -11,10 +11,18 @@ set -o errexit
 set -o nounset
 set -o pipefail
 
-releases=("v0.1.0" "v0.2.0" "v0.3.0" "v0.4.0" "v0.5.0" "v0.5.1" "v0.5.2")
+arg_cmd=${1-}
+if [[ -n "$arg_cmd" && "$arg_cmd" != "commits-only" ]]; then
+    echo "Error: Invalid argument '$arg_cmd'. Only 'commits-only' is allowed."
+    exit 1
+fi
+
+releases=($(git tag --list 'v*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V))
 
 chagelog_file="$(dirname $0)"/../docs/CHANGELOG.md
-chagelog_dir="$(dirname $0)"/../docs/changelogs
+chagelog_commits_file="$(dirname $0)"/../docs/CHANGELOG_commits.md
+chagelog_sum_file="$(dirname $0)"/../docs/CHANGELOG_summary.md
+
 chagelog_dir="/tmp/opct-changelogs"
 mkdir -p $chagelog_dir
 
@@ -62,8 +70,14 @@ function extract_jira_id() {
 first_commit=$(git rev-list --max-parents=0 HEAD)
 init_release=$first_commit
 for rel in "${releases[@]}"; do
+    echo "Processing release $rel"
+    if [[ "$rel" == *","* ]]; then
+        echo "Skipping release $rel due to invalid characters (commas)."
+        continue
+    fi
+
     ch_file=$chagelog_dir/$rel.md
-    echo -e "\n## OPCT [$rel](https://github.com/redhat-openshift-ecosystem/opct/releases/tag/$rel)\n" > "$ch_file"
+    echo -e "\n### OPCT [$rel](https://github.com/redhat-openshift-ecosystem/opct/releases/tag/$rel)\n" > "$ch_file"
 
     # read the git log with changes between releases (from/to)
     git log --pretty=oneline --abbrev-commit --no-decorate --no-color "$init_release"..tags/"$rel" | \
@@ -92,7 +106,7 @@ done
 
 # devel (since last release - need to run from 'main' branch)
 ch_file=$chagelog_dir/devel.md
-echo -e "\n## OPCT Development\n" > "$ch_file"
+echo -e "\n### OPCT Development\n" > "$ch_file"
 
 # Process OPCT repo
 git log --pretty=oneline --abbrev-commit --no-decorate --no-color "$init_release"..HEAD | \
@@ -125,17 +139,32 @@ Changelog by release for [CLI (OPCT)][project-cli] project.
 
 EOF
 
+# if summary file exists, insert it
+if [[ -f ${chagelog_sum_file} ]];
+then
+    cat ${chagelog_sum_file} >> "$chagelog_file"
+fi
+
+echo -e "\n## Releases Changes" > "$chagelog_commits_file"
+
 # devel.md will be first
-cat $chagelog_dir/devel.md >> "$chagelog_file"
+cat $chagelog_dir/devel.md >> "$chagelog_commits_file"
 
 # then append the releases by reverse order (newest version/file first)
 for rev_releases in $(ls -r $chagelog_dir --ignore=devel.md); do
-    echo -e "\n" >> "$chagelog_file"
-    cat $chagelog_dir/"$rev_releases" >> "$chagelog_file"
+    echo -e "\n" >> "$chagelog_commits_file"
+    cat $chagelog_dir/"$rev_releases" >> "$chagelog_commits_file"
 done
 
-echo -e "\n\n > This page is generated automatically by CI/hack-generate-changelog.sh\n\n" >> "$chagelog_file"
+# Saving the commits file
+cat $chagelog_commits_file >> $chagelog_file
 
+echo -e "\n\n > This page is generated automatically by CI/hack-generate-changelog.sh\n\n" >> "$chagelog_file"
 
 # TODO: create plugin changelog
 #plugin_releases=("v0.1.1" "v0.2.2" "v0.3.0" "v0.4.0")
+
+echo "Removing changelog dir ${chagelog_dir}..."
+if [[ -n "${chagelog_dir}" && -d "${chagelog_dir}" ]]; then
+    rm -rvf "${chagelog_dir}"
+fi