From bae121c8ffb1c107ce779946b994173b1ac3e7d7 Mon Sep 17 00:00:00 2001 From: PingDavidR Date: Thu, 22 Jan 2026 13:46:42 -0600 Subject: [PATCH 1/3] Add shared-configs module --- .gitmodules | 3 +++ shared-configs | 1 + 2 files changed, 4 insertions(+) create mode 100644 .gitmodules create mode 160000 shared-configs diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000..f6179c48 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "shared-configs"] + path = shared-configs + url = git@github-emu:ping-internal/cdi-shared-configs.git diff --git a/shared-configs b/shared-configs new file mode 160000 index 00000000..e3af3bc3 --- /dev/null +++ b/shared-configs @@ -0,0 +1 @@ +Subproject commit e3af3bc3f96d25221e04945029294fe14a22dd38 From 9e909c4592840f9c006792fcd4d804e21363e198 Mon Sep 17 00:00:00 2001 From: PingDavidR Date: Thu, 22 Jan 2026 13:48:35 -0600 Subject: [PATCH 2/3] initializing release notes structure --- .changelog/FORMAT_EXAMPLES.md | 76 +++++++++++++++++++++++ .changelog/README.md | 110 ++++++++++++++++++++++++++++++++++ release-notes/README.md | 19 ++++++ 3 files changed, 205 insertions(+) create mode 100644 .changelog/FORMAT_EXAMPLES.md create mode 100644 .changelog/README.md create mode 100644 release-notes/README.md diff --git a/.changelog/FORMAT_EXAMPLES.md b/.changelog/FORMAT_EXAMPLES.md new file mode 100644 index 00000000..3f8de6c8 --- /dev/null +++ b/.changelog/FORMAT_EXAMPLES.md @@ -0,0 +1,76 @@ +# Changelog Entry Format Examples + +This directory contains changelog entries using the structured key-value format. + +## Filename Format + +The name of the changelog file will comprise of `pr-` followed by the PR number, appended with a `.txt` extension. + +For example: `pr-2345.txt` + +## Format + +Each changelog entry file should follow this format: + +```plaintext +type: +description: +pr: +ticket: +``` + +## Valid Types + +- breaking +- feature +- enhancement +- bugfix +- note +- security +- deprecation +- internal (tracked but not included in release notes) + +## Field Descriptions + +- **type**: The type of change (required) +- **description**: A clear description of the change (required) +- **pr**: The pull request number (required, or can be inferred from filename) +- **ticket**: The Jira ticket (CDI-### or PDI-###), or N/A if not applicable (required) + +## Examples + +### Feature with Jira ticket + +```plaintext +type: feature +description: Added new calculator function for advanced mathematical operations +pr: 123 +ticket: CDI-456 +``` + +### Bug fix without Jira ticket + +```plaintext +type: bugfix +description: Fixed issue where division by zero caused application crash +pr: 124 +ticket: N/A +``` + +### Breaking change with Jira ticket + +```plaintext +type: breaking +description: Removed deprecated legacy API endpoints +pr: 125 +ticket: PDI-789 +``` + +### Internal change (not included in release notes) + +```plaintext +type: internal +description: Refactored internal helper functions for better code organization +pr: 126 +ticket: N/A +``` diff --git a/.changelog/README.md b/.changelog/README.md new file mode 100644 index 00000000..f5a663c0 --- /dev/null +++ b/.changelog/README.md @@ -0,0 +1,110 @@ +# Changelog Management + +This directory contains changelog entries for changes made to the repository. The changelog entries are used to generate release notes when a new version is released. + +## How It Works + +1. When you create a PR, you should create a changelog file named `pr-{PR_NUMBER}.txt` in this directory. +2. If you don't create one, GitHub Actions will automatically create one for you. +3. The changelog file should follow the format shown in the examples below. +4. During the release process, all changelog files are combined to generate release notes. +5. After release, all changelog files are moved to the `archive/{version}` directory. + +## Changelog File Format + +Changelog files use a simple key-value format. Each file should contain the following fields: + +- `type:` - The type of change +- `description:` - A description of the change +- `pr:` - The pull request number +- `ticket:` - The Jira ticket (or N/A if not applicable) + +The recognized change types are: + +- `breaking` - Breaking changes that require user action +- `feature` - New features +- `enhancement` - Enhancements to existing functionality +- `bugfix` - Bug fixes +- `note` - General notes about the release +- `security` - Security-related changes +- `deprecation` - Deprecated features or functionality +- `internal` - Internal changes that are tracked but not included in release notes + +## Creating a Changelog Entry + +You can create a changelog entry using one of these two methods: + +1. **Using the script**: + + ```bash + ./scripts/create-changelog-entry.sh "Your change description" [JIRA-TICKET] + ``` + + Example: + + ```bash + ./scripts/create-changelog-entry.sh 123 feature "Added new calculator function" CDI-456 + ``` + +2. **Manually creating the file**: + Create a file named `pr-{PR_NUMBER}.txt` in the `.changelog` directory with the following format: + + ```plaintext + type: + description: + pr: + ticket: CDI-####, PDI-####, or N/A + ``` + + Where: + - `type` is one of: breaking, feature, enhancement, bugfix, note, security, deprecation, internal + - `description` is a clear description of the change + - `pr` is the pull request number + - `ticket` is the Jira ticket (CDI-## or PDI-##) or N/A if not applicable + +## Examples + +```plaintext +type: feature +description: Added new calculator function `Multiply` for multiplication of two numbers +pr: 123 +ticket: CDI-456 +``` + +```plaintext +type: bugfix +description: Fixed issue where division by zero would cause application crash +pr: 124 +ticket: N/A +``` + +## Release Process + +The release process for managing changelog entries involves the following steps: + +1. **Generate Release Notes**: Use the `generate-release-notes.sh` script to create release notes for the new version: + + ```bash + ./shared-configs/release-notes/scripts/generate-release-notes.sh vX.Y.Z + ``` + + This scriptcreates: + - `GITHUB_RELEASE_NOTES.md` in the repository root + - `release-notes/vX.Y.Z/RELEASE_NOTES.adoc` for portal or other documentation + - `release-notes/vX.Y.Z/GITHUB_RELEASE.md` for GitHub releases + +2. **Review the Generated Files**: Verify that the generated files contain the correct information: + - Confirm that all changes are properly categorized + - PRs labeled as `internal` are excluded from the release notes + - Check that the `release-notes/vX.Y.Z/` directory contains all expected files + - Verify the content of `GITHUB_RELEASE_NOTES.md` (or `.adoc`) + +3. **Archive Changelog Entries**: When releasing, archive the changelog entries using: + + ```bash + ./scripts/archive-changelogs.sh vX.Y.Z + ``` + + This command moves all processed changelog files to the `.changelog/archive/vX.Y.Z/` directory. + +This process ensures that each release contains only the changes made since the last release, and that all changelog entries are properly archived for historical reference. diff --git a/release-notes/README.md b/release-notes/README.md new file mode 100644 index 00000000..e4696d45 --- /dev/null +++ b/release-notes/README.md @@ -0,0 +1,19 @@ +# Release Notes + +This directory is used to store release notes for each version. + +The release notes for each version are stored in a subdirectory named after the release tag, following the format `vX.Y.Z`. + +Each release directory will contain the following two files: + +* `GITHUB_RELEASE.md`: The release notes formatted for GitHub Releases. +* `RELEASE_NOTES.adoc`: The release notes in AsciiDoc format. + +For example, the release notes for version 1.2.3 would be structured as follows: + +```text +release-notes/ +└── v1.2.3/ + ├── GITHUB_RELEASE.md + └── RELEASE_NOTES.adoc +``` From 37c620fa6c17c7da9e9e6c217cbaf61e8de0c74d Mon Sep 17 00:00:00 2001 From: PingDavidR Date: Wed, 28 Jan 2026 13:37:47 -0600 Subject: [PATCH 3/3] moved README to shared-configs, updated submodule --- .changelog/FORMAT_EXAMPLES.md | 85 +++++++++++++------------- .changelog/README.md | 110 ---------------------------------- .changelog/pr-153.txt | 3 + shared-configs | 2 +- 4 files changed, 49 insertions(+), 151 deletions(-) delete mode 100644 .changelog/README.md create mode 100644 .changelog/pr-153.txt diff --git a/.changelog/FORMAT_EXAMPLES.md b/.changelog/FORMAT_EXAMPLES.md index 3f8de6c8..73130483 100644 --- a/.changelog/FORMAT_EXAMPLES.md +++ b/.changelog/FORMAT_EXAMPLES.md @@ -1,6 +1,6 @@ # Changelog Entry Format Examples -This directory contains changelog entries using the structured key-value format. +This directory contains changelog entries using markdown format with code blocks. ## Filename Format @@ -10,67 +10,72 @@ For example: `pr-2345.txt` ## Format -Each changelog entry file should follow this format: - -```plaintext -type: -description: -pr: -ticket: -``` +Each changelog entry file uses markdown code blocks with the `release-note:` syntax. Multiple entries can be included in a single file, each in its own code block. ## Valid Types -- breaking +- breaking-change - feature - enhancement -- bugfix +- bug - note - security - deprecation +- new-resource (new Terraform resource) +- new-data-source (new Terraform data source) +- new-guide (new Terraform guide) - internal (tracked but not included in release notes) -## Field Descriptions +## Examples -- **type**: The type of change (required) -- **description**: A clear description of the change (required) -- **pr**: The pull request number (required, or can be inferred from filename) -- **ticket**: The Jira ticket (CDI-### or PDI-###), or N/A if not applicable (required) +### Feature example -## Examples +````plaintext +```release-note:feature +Added new calculator function for advanced mathematical operations +``` +```` -### Feature with Jira ticket +### Bug fix example -```plaintext -type: feature -description: Added new calculator function for advanced mathematical operations -pr: 123 -ticket: CDI-456 +````plaintext +```release-note:bug +Fixed issue where division by zero caused application crash ``` +```` -### Bug fix without Jira ticket +### Breaking change example -```plaintext -type: bugfix -description: Fixed issue where division by zero caused application crash -pr: 124 -ticket: N/A +````plaintext +```release-note:breaking-change +Removed deprecated legacy API endpoints ``` +```` -### Breaking change with Jira ticket +### Enhancement with resource reference + +````plaintext +```release-note:enhancement +`resource/pingone_risk_predictor`: Added the `predictor_device.should_validate_payload_signature` field to enforce requirement that the Signals SDK payload be provided as a signed JWT. +``` +```` + +### Multiple entries in one file + +````plaintext +```release-note:note +bump `github.com/example/sdk` 0.12.1 => 0.12.2 +``` -```plaintext -type: breaking -description: Removed deprecated legacy API endpoints -pr: 125 -ticket: PDI-789 +```release-note:bug +`resource/example_gateway`: Fixed error when configuring gateways. ``` +```` ### Internal change (not included in release notes) -```plaintext -type: internal -description: Refactored internal helper functions for better code organization -pr: 126 -ticket: N/A +````plaintext +```release-note:internal +Refactored internal helper functions for better code organization ``` +```` diff --git a/.changelog/README.md b/.changelog/README.md deleted file mode 100644 index f5a663c0..00000000 --- a/.changelog/README.md +++ /dev/null @@ -1,110 +0,0 @@ -# Changelog Management - -This directory contains changelog entries for changes made to the repository. The changelog entries are used to generate release notes when a new version is released. - -## How It Works - -1. When you create a PR, you should create a changelog file named `pr-{PR_NUMBER}.txt` in this directory. -2. If you don't create one, GitHub Actions will automatically create one for you. -3. The changelog file should follow the format shown in the examples below. -4. During the release process, all changelog files are combined to generate release notes. -5. After release, all changelog files are moved to the `archive/{version}` directory. - -## Changelog File Format - -Changelog files use a simple key-value format. Each file should contain the following fields: - -- `type:` - The type of change -- `description:` - A description of the change -- `pr:` - The pull request number -- `ticket:` - The Jira ticket (or N/A if not applicable) - -The recognized change types are: - -- `breaking` - Breaking changes that require user action -- `feature` - New features -- `enhancement` - Enhancements to existing functionality -- `bugfix` - Bug fixes -- `note` - General notes about the release -- `security` - Security-related changes -- `deprecation` - Deprecated features or functionality -- `internal` - Internal changes that are tracked but not included in release notes - -## Creating a Changelog Entry - -You can create a changelog entry using one of these two methods: - -1. **Using the script**: - - ```bash - ./scripts/create-changelog-entry.sh "Your change description" [JIRA-TICKET] - ``` - - Example: - - ```bash - ./scripts/create-changelog-entry.sh 123 feature "Added new calculator function" CDI-456 - ``` - -2. **Manually creating the file**: - Create a file named `pr-{PR_NUMBER}.txt` in the `.changelog` directory with the following format: - - ```plaintext - type: - description: - pr: - ticket: CDI-####, PDI-####, or N/A - ``` - - Where: - - `type` is one of: breaking, feature, enhancement, bugfix, note, security, deprecation, internal - - `description` is a clear description of the change - - `pr` is the pull request number - - `ticket` is the Jira ticket (CDI-## or PDI-##) or N/A if not applicable - -## Examples - -```plaintext -type: feature -description: Added new calculator function `Multiply` for multiplication of two numbers -pr: 123 -ticket: CDI-456 -``` - -```plaintext -type: bugfix -description: Fixed issue where division by zero would cause application crash -pr: 124 -ticket: N/A -``` - -## Release Process - -The release process for managing changelog entries involves the following steps: - -1. **Generate Release Notes**: Use the `generate-release-notes.sh` script to create release notes for the new version: - - ```bash - ./shared-configs/release-notes/scripts/generate-release-notes.sh vX.Y.Z - ``` - - This scriptcreates: - - `GITHUB_RELEASE_NOTES.md` in the repository root - - `release-notes/vX.Y.Z/RELEASE_NOTES.adoc` for portal or other documentation - - `release-notes/vX.Y.Z/GITHUB_RELEASE.md` for GitHub releases - -2. **Review the Generated Files**: Verify that the generated files contain the correct information: - - Confirm that all changes are properly categorized - - PRs labeled as `internal` are excluded from the release notes - - Check that the `release-notes/vX.Y.Z/` directory contains all expected files - - Verify the content of `GITHUB_RELEASE_NOTES.md` (or `.adoc`) - -3. **Archive Changelog Entries**: When releasing, archive the changelog entries using: - - ```bash - ./scripts/archive-changelogs.sh vX.Y.Z - ``` - - This command moves all processed changelog files to the `.changelog/archive/vX.Y.Z/` directory. - -This process ensures that each release contains only the changes made since the last release, and that all changelog entries are properly archived for historical reference. diff --git a/.changelog/pr-153.txt b/.changelog/pr-153.txt new file mode 100644 index 00000000..9ae33612 --- /dev/null +++ b/.changelog/pr-153.txt @@ -0,0 +1,3 @@ +```release-note:internal +add submodule and implement common changelog process +``` diff --git a/shared-configs b/shared-configs index e3af3bc3..aebba7c1 160000 --- a/shared-configs +++ b/shared-configs @@ -1 +1 @@ -Subproject commit e3af3bc3f96d25221e04945029294fe14a22dd38 +Subproject commit aebba7c1c5428c492e7be4806be42c1d0ce1cf2d