From b7316cee205aa8ccb80cd5b28d1850f8e3885868 Mon Sep 17 00:00:00 2001 From: Paul van Brouwershaven Date: Wed, 6 Nov 2024 16:44:01 +0100 Subject: [PATCH 1/3] Initial readme describing version control process --- README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3b15286 --- /dev/null +++ b/README.md @@ -0,0 +1,82 @@ +# CP/CPS Version Control Process + +This document outlines the version control process for updating the Entrust CP/CPS documents using Git. + +## Branching Strategy + +- **Main Branch**: The `main` branch contains the latest published version of CP/CPS documents (e.g., version 1.0). +- **Release Branches**: For each upcoming version, create a new branch from `main` named `vX.Y` (e.g., `v1.1` for version 1.1). Release branches are where approved changes accumulate until the release is finalized. +- **Feature Branches**: Each change is developed in a separate feature branch created from the relevant release branch (e.g., `v1.1`). Feature branch names should be descriptive and lowercase (e.g., `ballot-sc-001` or `jira-ec-123`). + +## Process Steps + +1. **Create Release Branch**: When preparing a new version, create a release branch from `main` (e.g., `v1.1`). This branch serves as the staging area for the next release. + +2. **Develop Changes in Feature Branches**: For each change: + - Create a feature branch from the release branch (e.g., `v1.1`) with a clear name, such as `ballot-sc-001` or `jira-ec-123`. + - Implement the change, and submit it for review and approval. + +3. **Review and Approval**: Feature branches must be reviewed and approved before they can be merged into the release branch. Once approved, changes are queued in the release branch for the next version. This ensures only vetted changes are included in a release. + +4. **Adjust Target for Deferred Changes**: If a feature (e.g., `jira-ec-123`) is deferred to a future release, update its target branch to the subsequent release branch (e.g., `v1.2`). + +5. **Merge into Release Branch**: Once all changes for the release are confirmed, approved feature branches are merged into the release branch (e.g., `v1.1`). Feature branches can be merged in any order, allowing flexibility in release planning. + +6. **Protect Release Branch**: Release branches (e.g., `v1.1`, `v1.2`) are protected, requiring pull requests and approvals for any modifications. + +7. **Final Merge to Main**: Once the release is complete, merge the release branch (e.g., `v1.1`) into `main` for publication. No additional approvals are needed for this final merge, as all changes in the release branch have been reviewed. + +## Example Git Flow + +The diagram below visualizes the process, showing `ballot-sc-001` and `ballot-sc-002` as approved changes merged into `v1.1`. The feature `jira-ec-123` is initially developed from `v1.1` but ultimately deferred to `v1.2`: + +```mermaid +gitGraph TB: + commit id: "v1.0" tag: "main (1.0)" + branch v1.1 order: 1 + checkout v1.1 + commit id: "Start v1.1 release prep." tag: "v1.1" + + checkout v1.1 + branch ballot-sc-001 order: 5 + checkout ballot-sc-001 + commit id: "Implement SC-001" + checkout v1.1 + merge ballot-sc-001 + + checkout v1.1 + + branch jira-ec-123 order: 6 + checkout jira-ec-123 + commit id: "Implement EC-123" + commit id: "Address feedback" + + checkout v1.1 + branch ballot-sc-002 order: 4 + checkout ballot-sc-002 + commit id: "Implement SC-002" + checkout v1.1 + merge ballot-sc-002 + + checkout main + merge v1.1 tag: "v1.1 release" + + checkout main + branch v1.2 order: 2 + commit id: "Start v1.2 release prep." tag: "v1.2" + + checkout jira-ec-123 + commit id: "Fix spelling" + + checkout v1.2 + merge jira-ec-123 + + checkout main + merge v1.2 tag: "v1.2 release" +``` + +This diagram shows: +- `main` branch with the published versions. +- `v1.1` branch for the 1.1 release, where feature branches `ballot-sc-001` and `ballot-sc-002` are approved and merged. +- `jira-ec-123` is initially created from `v1.1` but later retargeted to `v1.2`, so it merges into `v1.2` instead. +- After all changes are finalized, `v1.1` is merged into `main` to release version 1.1. Later, `v1.2` follows the same process. From 5b3c09f734965269cd0a470d5e3b5107846c6415 Mon Sep 17 00:00:00 2001 From: Paul van Brouwershaven Date: Wed, 6 Nov 2024 17:19:09 +0100 Subject: [PATCH 2/3] Add introduction and info about directory structure --- README.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3b15286..e77c223 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,29 @@ -# CP/CPS Version Control Process +# Entrust ECS CP/CPS Repository + +This repository is designed to manage and update the Entrust ECS CP/CPS (Certification Practice Statement) documents. The CP/CPS document is written in Markdown and built into PDF and Word formats via a build action utilizing Pandoc. + +## Directory Structure + +The repository is organized into the following directories: + +- **.github/**: Contains GitHub Actions workflows to build and test the document(s). +- **filters/**: Includes additional Lua Pandoc filters. +- **templates/**: Holds the docx and latex templates for Pandoc and some dependent files used by these templates. +- **tests/**: Contains test files used to verify the document structure. +- **tools/**: Contains scripts used to check or modify the markdown document. +- **entrust.md**: The actual Entrust CP/CPS source document. + +## CP/CPS Version Control Process This document outlines the version control process for updating the Entrust CP/CPS documents using Git. -## Branching Strategy +### Branching Strategy - **Main Branch**: The `main` branch contains the latest published version of CP/CPS documents (e.g., version 1.0). - **Release Branches**: For each upcoming version, create a new branch from `main` named `vX.Y` (e.g., `v1.1` for version 1.1). Release branches are where approved changes accumulate until the release is finalized. - **Feature Branches**: Each change is developed in a separate feature branch created from the relevant release branch (e.g., `v1.1`). Feature branch names should be descriptive and lowercase (e.g., `ballot-sc-001` or `jira-ec-123`). -## Process Steps +### Process Steps 1. **Create Release Branch**: When preparing a new version, create a release branch from `main` (e.g., `v1.1`). This branch serves as the staging area for the next release. @@ -26,7 +41,7 @@ This document outlines the version control process for updating the Entrust CP/C 7. **Final Merge to Main**: Once the release is complete, merge the release branch (e.g., `v1.1`) into `main` for publication. No additional approvals are needed for this final merge, as all changes in the release branch have been reviewed. -## Example Git Flow +### Example Git Flow The diagram below visualizes the process, showing `ballot-sc-001` and `ballot-sc-002` as approved changes merged into `v1.1`. The feature `jira-ec-123` is initially developed from `v1.1` but ultimately deferred to `v1.2`: From 1ec5a6db9a79f522271e2ec9e33e83775eb5d978 Mon Sep 17 00:00:00 2001 From: Paul van Brouwershaven Date: Fri, 15 Nov 2024 14:17:39 +0100 Subject: [PATCH 3/3] Only run action when relevant --- .github/workflows/check-no-stipulation.yml | 13 ++++++++++++- .github/workflows/check-sections.yml | 13 ++++++++++++- 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/.github/workflows/check-no-stipulation.yml b/.github/workflows/check-no-stipulation.yml index 5037e02..3bc64cf 100644 --- a/.github/workflows/check-no-stipulation.yml +++ b/.github/workflows/check-no-stipulation.yml @@ -1,8 +1,19 @@ name: Check for no stipulation on: push: - branches: ["main"] + paths: + - "tools/**" + - "tests/**" + - "*.md" + paths-ignore: + - 'README.md' pull_request: + paths: + - "tools/**" + - "tests/**" + - "*.md" + paths-ignore: + - 'README.md' jobs: check-no-stipulation: diff --git a/.github/workflows/check-sections.yml b/.github/workflows/check-sections.yml index 963008f..6008031 100644 --- a/.github/workflows/check-sections.yml +++ b/.github/workflows/check-sections.yml @@ -1,8 +1,19 @@ name: Check Sections on: push: - branches: ["main"] + paths: + - "tools/**" + - "tests/**" + - "*.md" + paths-ignore: + - 'README.md' pull_request: + paths: + - "tools/**" + - "tests/**" + - "*.md" + paths-ignore: + - 'README.md' jobs: check-sections: