- add GitHub workflow and changes to scripts to support milestone branches (i.e. custom scalars, etc)

Author: jasonbahl

.github/workflows/generate-changeset.yml

@@ -0,0 +1,202 @@
+# Milestone Branch Workflow
+
+This document outlines the requirements and implementation details for the Milestone Branch workflow.
+
+## Overview
+
+The Milestone Branch workflow allows for the development of larger features that span multiple PRs. It provides a way to collect changesets for a specific feature or milestone while keeping them separate from the main development branch until the feature is complete.
+
+## Branch Naming Convention
+
+Milestone branches follow this naming convention:
+
+```
+milestone/feature-name
+```
+
+For example:
+- `milestone/custom-scalars`
+- `milestone/media-refactor`
+- `milestone/new-api`
+
+The feature name should use kebab-case (lowercase with hyphens).
+
+## Workflow Steps
+
+The workflow consists of the following steps:
+
+1. **Create Milestone Branch**: Create a branch with the `milestone/` prefix for your feature.
+2. **Create GitHub Milestone**: Create a GitHub Milestone with the same name as your feature.
+3. **Create Issues**: Create issues for each part of the implementation and assign them to the GitHub Milestone.
+4. **Create PRs**: As you implement each part, create PRs against the milestone branch.
+5. **Collect Changesets**: Each merged PR automatically generates a changeset in the milestone branch.
+6. **Track Progress**: A PR from the milestone branch to develop is automatically created/updated with:
+   - A list of all changes (from changesets)
+   - Progress information from the GitHub Milestone
+   - Links to the Milestone for more details
+7. **Final Merge**: When the milestone is complete, merge the milestone branch to develop.
+
+## Changeset Generation
+
+When a PR is merged to a milestone branch, the changeset generation workflow:
+
+1. Detects that the target branch is a milestone branch
+2. Generates a changeset with branch information
+3. Commits the changeset to the milestone branch
+4. Generates release notes for the milestone branch
+5. Creates or updates a PR from the milestone branch to develop
+
+## Milestone PR Management
+
+The workflow automatically creates and maintains a PR from the milestone branch to the develop branch:
+
+1. **PR Title**: `feat: feature-name 🚀`
+2. **PR Body**: Contains:
+   - Milestone information and progress
+   - Link to the GitHub Milestone
+   - List of changes from changesets
+   - Explanation of the milestone
+
+This PR serves as a preview of what will be merged to develop when the milestone is complete.
+
+## GitHub Milestone Integration
+
+The workflow integrates with GitHub Milestones:
+
+1. **Milestone Assignment**: PRs targeting the milestone branch are automatically assigned to the corresponding GitHub Milestone.
+2. **Progress Tracking**: The milestone PR includes progress information from the GitHub Milestone (e.g., "5/10 issues completed (50%)").
+3. **Milestone Links**: The milestone PR includes links to the GitHub Milestone for more details.
+
+## Changeset Handling
+
+When a milestone branch is eventually merged to develop:
+
+1. All changesets from the milestone branch are included in the develop branch.
+2. The existing develop workflow kicks in, updating the PR from develop to main with all changesets.
+3. The changesets maintain their original metadata, including the branch they were created in.
+
+This ensures that the release notes for the next release include all changes, whether they came from direct PRs to develop or from milestone branches.
+
+## Example Workflow
+
+Here's an example of how to use the milestone branch workflow:
+
+1. **Create a Milestone Branch**:
+   ```bash
+   git checkout develop
+   git pull
+   git checkout -b milestone/custom-scalars
+   git push -u origin milestone/custom-scalars
+   ```
+
+2. **Create a GitHub Milestone**:
+   - Go to GitHub > Issues > Milestones > New Milestone
+   - Title: "custom-scalars"
+   - Description: "Implement custom scalar types for GraphQL schema"
+   - Due date: (optional)
+   - Click "Create milestone"
+
+3. **Create Issues**:
+   - Create issues for each part of the implementation
+   - Assign them to the "custom-scalars" milestone
+   - Example issues:
+     - "Implement DateTime scalar"
+     - "Implement Email scalar"
+     - "Implement Color scalar"
+
+4. **Create PRs**:
+   - Implement each part in a separate branch
+   - Create PRs targeting the `milestone/custom-scalars` branch
+   - Example PR titles:
+     - "feat: Implement DateTime scalar"
+     - "feat: Implement Email scalar"
+     - "feat: Implement Color scalar"
+
+5. **Review and Merge PRs**:
+   - Review and merge PRs to the milestone branch
+   - Each merged PR automatically generates a changeset
+   - The milestone PR to develop is automatically updated
+
+6. **Complete the Milestone**:
+   - When all issues are resolved, merge the milestone PR to develop
+   - The develop branch now includes all changes from the milestone
+   - The existing develop workflow updates the PR from develop to main
+
+## Benefits
+
+The milestone branch workflow provides several benefits:
+
+1. **Feature Isolation**: Develop large features in isolation without affecting the main development branch.
+2. **Progress Tracking**: Track progress of large features using GitHub Milestones.
+3. **Changeset Collection**: Collect changesets for a specific feature or milestone.
+4. **Preview Changes**: Preview what will be merged to develop when the milestone is complete.
+5. **Collaborative Development**: Allow multiple developers to work on different parts of the same feature.
+6. **Detailed Release Notes**: Generate detailed release notes for the milestone.
+
+## Considerations
+
+When using the milestone branch workflow, consider the following:
+
+1. **Branch Synchronization**: Regularly sync the milestone branch with develop to avoid divergence.
+2. **Milestone Scope**: Keep milestones focused on a specific feature or set of related changes.
+3. **PR Size**: Even within a milestone, keep PRs small and focused for easier review.
+4. **Documentation**: Document the milestone's purpose and scope in the GitHub Milestone description.
+5. **Testing**: Thoroughly test the milestone branch before merging to develop.
+
+## GitHub Action Implementation
+
+The milestone branch workflow is implemented in the `generate-changeset.yml` workflow:
+
+```yaml
+name: Generate Changeset
+
+on:
+  pull_request_target:
+    types: [closed]
+    branches:
+      - develop
+      - 'milestone/**'  # Support for milestone branches
+  workflow_dispatch:
+    # ...
+
+jobs:
+  generate-changeset:
+    # ...
+    steps:
+      # ...
+      - name: Determine target branch
+        id: target_branch
+        run: |
+          # Check if this is a milestone branch
+          if [[ "${TARGET_BRANCH}" == milestone/* ]]; then
+            echo "is_milestone=true" >> $GITHUB_OUTPUT
+            # Extract milestone name from branch name
+            MILESTONE_NAME=$(echo "${TARGET_BRANCH}" | sed 's/^milestone\///')
+            echo "milestone_name=${MILESTONE_NAME}" >> $GITHUB_OUTPUT
+          else
+            echo "is_milestone=false" >> $GITHUB_OUTPUT
+          fi
+      
+      # Generate changeset with branch information
+      - name: Generate changeset for current PR
+        run: |
+          node scripts/generate-changeset.js \
+            --pr="${{ steps.pr_info.outputs.pr_number }}" \
+            --title="${{ steps.pr_info.outputs.pr_title }}" \
+            --author="${{ steps.pr_info.outputs.pr_author }}" \
+            --body="${{ steps.pr_info.outputs.pr_body }}" \
+            --branch="${{ steps.target_branch.outputs.name }}"
+      
+      # For milestone branches, create/update PR to develop
+      - name: Create/Update milestone PR to develop
+        if: steps.target_branch.outputs.is_milestone == 'true'
+        # ...
+```
+
+## Next Steps and Considerations
+
+- Create GitHub Milestones for each milestone branch
+- Regularly sync milestone branches with develop
+- Consider adding a workflow to automatically create milestone branches and GitHub Milestones
+- Add support for milestone branch deletion after merging to develop
+- Consider adding a workflow to automatically close GitHub Milestones when the milestone branch is merged to develop 

.github/workflows/milestone-branch-workflow.md

@@ -422,6 +422,21 @@ For visual representations of the workflows, see [docs/WORKFLOW_VISUALIZATION.md
 7. The release management workflow creates a tag and GitHub release
 8. The plugin is deployed to the appropriate environments
 
+### Milestone Branch Workflow
+
+For larger features that span multiple PRs, we use a milestone branch workflow:
+
+1. Create a milestone branch with the `milestone/` prefix (e.g., `milestone/custom-scalars`)
+2. Create a GitHub Milestone with the same name (e.g., "custom-scalars")
+3. Create issues for each part of the implementation and assign them to the GitHub Milestone
+4. Create PRs against the milestone branch
+5. When PRs are merged to the milestone branch, changesets are automatically generated
+6. A PR from the milestone branch to `develop` is automatically created/updated
+7. When the milestone is complete, merge the milestone branch to `develop`
+8. The existing workflow will include the milestone changes in the next release
+
+For more details, see [Milestone Branch Workflow](.github/workflows/milestone-branch-workflow.md).
+
 ## Local Testing
 
 You can test the scripts locally:

README.md

@@ -21,6 +21,9 @@
 ## Workflows
 
 - **generate-changeset.yml**: Automatically generates a changeset file when a PR is merged to develop.
+  - Now supports milestone branches with the `milestone/` prefix
+  - Automatically creates/updates a PR from the milestone branch to develop
+  - Integrates with GitHub Milestones for progress tracking
 - **release-management.yml**: Handles version bumping, changelog updates, and release creation when changes are merged to main.
   - Now includes improved sync between main and develop branches after releases
     - Uses a non-fast-forward merge strategy with a descriptive commit message
@@ -43,6 +46,7 @@
   - Changeset generation process with temporary file handling
   - Release management workflow
   - Deployment process
+  - Milestone branch workflow
 - Added examples and usage instructions for all scripts
 - Documented breaking change detection and handling
 - Added information about the new `generate-release-notes.js` script and how to use it locally
@@ -73,6 +77,11 @@
 
 ## Recent Updates
 
+- **Milestone Branch Support**: Added support for milestone branches with the `milestone/` prefix.
+  - Allows for development of larger features that span multiple PRs
+  - Automatically creates/updates a PR from the milestone branch to develop
+  - Integrates with GitHub Milestones for progress tracking
+  - Provides detailed release notes for milestone branches
 - **Environment Variables Support**: Added support for environment variables (`REPO_URL` and `GITHUB_TOKEN`) to simplify configuration and usage of the release notes script.
 - **Contributor Recognition**: Enhanced release notes to include a contributors section with special recognition for first-time contributors.
 - **GitHub Workflow Improvements**: Updated the GitHub workflow to use environment variables instead of command-line arguments, making it cleaner and more maintainable.

SUMMARY.md

@@ -220,4 +220,84 @@ gitGraph
     merge main id: "Sync v1.1.0 back to develop"
 ```
 
+## Standard Workflow
+
+```mermaid
+graph TD
+    A[Feature Branch] -->|Create PR| B[develop]
+    B -->|Merge PR| C[Generate Changeset]
+    C -->|Commit Changeset| B
+    B -->|Create/Update PR| D[main]
+    D -->|Merge PR| E[Release Management]
+    E -->|Version Bump| F[Create Tag]
+    F -->|Push Tag| G[Deploy]
+    G -->|Create GitHub Release| H[WordPress.org SVN]
+    E -->|Sync Changes| B
+```
+
+## Milestone Branch Workflow
+
+```mermaid
+graph TD
+    A[Feature Branch 1] -->|Create PR| B[milestone/feature]
+    C[Feature Branch 2] -->|Create PR| B
+    D[Feature Branch 3] -->|Create PR| B
+    B -->|Merge PR| E[Generate Changeset]
+    E -->|Commit Changeset| B
+    B -->|Create/Update PR| F[develop]
+    F -->|Merge PR| G[Generate Changeset]
+    G -->|Commit Changeset| F
+    F -->|Create/Update PR| H[main]
+    H -->|Merge PR| I[Release Management]
+    I -->|Version Bump| J[Create Tag]
+    J -->|Push Tag| K[Deploy]
+    K -->|Create GitHub Release| L[WordPress.org SVN]
+    I -->|Sync Changes| F
+```
+
+## Milestone Branch Integration
+
+```mermaid
+sequenceDiagram
+    participant FB as Feature Branches
+    participant MB as Milestone Branch
+    participant GH as GitHub Actions
+    participant MS as GitHub Milestone
+    participant PR as Milestone PR
+    participant D as develop
+    
+    FB->>MB: Create PRs
+    MB->>GH: Merge PRs
+    GH->>MB: Generate changesets
+    GH->>MS: Update progress
+    GH->>PR: Update PR to develop
+    MB->>D: Merge when complete
+    D->>GH: Include milestone changes in next release
+```
+
+## Complete Workflow with Milestone Branches
+
+```mermaid
+graph TD
+    A[Feature Branch] -->|Create PR| B[develop]
+    C[Feature Branch 1] -->|Create PR| D[milestone/feature]
+    E[Feature Branch 2] -->|Create PR| D
+    F[Feature Branch 3] -->|Create PR| D
+    
+    B -->|Merge PR| G[Generate Changeset for develop]
+    D -->|Merge PR| H[Generate Changeset for milestone]
+    
+    G -->|Commit Changeset| B
+    H -->|Commit Changeset| D
+    
+    D -->|Create/Update PR| B
+    B -->|Create/Update PR| I[main]
+    
+    I -->|Merge PR| J[Release Management]
+    J -->|Version Bump| K[Create Tag]
+    K -->|Push Tag| L[Deploy]
+    L -->|Create GitHub Release| M[WordPress.org SVN]
+    J -->|Sync Changes| B
+```
+
 These visualizations provide a comprehensive overview of how the different components of the automation system interact. They can be especially helpful for new contributors to understand the workflow and for maintainers to identify potential areas for improvement. 

docs/WORKFLOW_VISUALIZATION.md

@@ -7,13 +7,15 @@
  *   node scripts/generate-changeset.js --pr=123 --title="feat: Add new feature" --author="username" --body="Description of the change"
  *   node scripts/generate-changeset.js --pr=123 --title="feat!: Add breaking feature" --author="username" --body="Description of the change"
  *   node scripts/generate-changeset.js --pr=123 --title="BREAKING CHANGE: Refactor API" --author="username" --body="Description of the change"
+ *   node scripts/generate-changeset.js --pr=123 --title="feat: Add new feature" --author="username" --body="Description of the change" --branch="milestone/custom-scalars"
  * 
  * Options:
  *   --pr         PR number
  *   --title      PR title
  *   --author     PR author
  *   --body       PR description
  *   --breaking   Explicitly mark as breaking change (true/false)
+ *   --branch     Branch where the changeset was created (default: develop)
  * 
  * Breaking Change Detection:
  *   Breaking changes are automatically detected from:
@@ -59,6 +61,11 @@ const argv = yargs(hideBin(process.argv))
     description: 'Whether the PR indicates a breaking change',
     default: false
   })
+  .option('branch', {
+    type: 'string',
+    description: 'Branch where the changeset was created',
+    default: 'develop'
+  })
   .help()
   .argv;
 
@@ -110,7 +117,7 @@ function isBreakingChange(title, body) {
  */
 async function generateChangeset() {
   // Extract PR information
-  const { pr, title, author, body } = argv;
+  const { pr, title, author, body, branch } = argv;
   const changeType = extractChangeType(title);
   const breaking = isBreakingChange(title, body);
 
@@ -121,6 +128,7 @@ async function generateChangeset() {
     author,
     type: changeType,
     breaking,
+    branch,
     description: body
   });