diff --git a/README.md b/README.md index 0f4a31a..34dadd7 100644 --- a/README.md +++ b/README.md @@ -409,6 +409,8 @@ This ensures a consistent and automated release process with proper versioning a For more details on the release process, see [.github/workflows/release-management.md](.github/workflows/release-management.md). +For visual representations of the workflows, see [docs/WORKFLOW_VISUALIZATION.md](docs/WORKFLOW_VISUALIZATION.md). + ## Development Process 1. Create a feature branch from `develop` diff --git a/SUGGESTIONS.md b/SUGGESTIONS.md index 5ca035a..cc7931b 100644 --- a/SUGGESTIONS.md +++ b/SUGGESTIONS.md @@ -60,7 +60,14 @@ Now that we've implemented all the suggested improvements, here are some additio 2. **Automated Testing**: Implement automated testing for the utility modules to ensure reliability. -3. **Workflow Visualization**: Add workflow visualization to help users understand the release process. +3. ✅ **Workflow Visualization**: Added workflow visualization to help users understand the release process. + - Created Mermaid diagrams for all major workflows + - Visualized the overall release process + - Illustrated script dependencies and data flow + - Provided visual representation of parallel execution + - Added branch strategy visualization + - Created diagrams for error handling strategy + - Documented utility module usage patterns 4. **Notification System**: Implement a notification system to alert team members about release status. diff --git a/docs/REUSABLE_WORKFLOWS_PLAN.md b/docs/REUSABLE_WORKFLOWS_PLAN.md new file mode 100644 index 0000000..f8dd9cf --- /dev/null +++ b/docs/REUSABLE_WORKFLOWS_PLAN.md @@ -0,0 +1,356 @@ +# Reusable Workflows Plan + +This document outlines a strategy for making our automation workflows reusable across multiple WPGraphQL repositories, including: + +- [wp-graphql/wp-graphql](https://github.com/wp-graphql/wp-graphql) +- [wp-graphql/wp-graphql-smart-cache](https://github.com/wp-graphql/wp-graphql-smart-cache) +- [wp-graphql/wpgraphql-ide](https://github.com/wp-graphql/wpgraphql-ide) +- [wp-graphql/wpgraphql-acf](https://github.com/wp-graphql/wpgraphql-acf) + +## Current State + +We've developed a robust set of workflows and scripts for: +- Changeset generation +- Release management +- Version bumping +- Changelog updates +- Documentation synchronization + +These workflows are currently implemented directly in this repository, but they could provide significant value across the entire WPGraphQL ecosystem. + +### Current Implementation Details + +Our current implementation includes: + +1. **GitHub Action Workflows**: + - `generate-changeset.yml`: Generates changesets when PRs are merged to develop + - `release-management.yml`: Handles version bumping, changelog updates, and release creation + - Other supporting workflows + +2. **Node.js Scripts**: + - `scripts/generate-changeset.js`: Creates changeset files from PR metadata + - `scripts/analyze-changesets.js`: Determines version bump type + - `scripts/generate-release-notes.js`: Formats release notes from changesets + - `scripts/bump-version.js`: Updates version numbers in files + - `scripts/update-changelog.js`: Updates CHANGELOG.md + - `scripts/update-readme.js`: Updates readme.txt + - `scripts/update-changelogs.js`: Updates both changelog files + - `scripts/update-upgrade-notice.js`: Updates upgrade notice section + +3. **Utility Modules**: + - `scripts/utils/env.js`: Environment variable handling + - `scripts/utils/changesets.js`: Changeset operations + +4. **Documentation**: + - `docs/WORKFLOW_VISUALIZATION.md`: Visual representations of workflows + - `README.md`: Usage instructions + - `SUMMARY.md`: Overview of accomplishments + - `SUGGESTIONS.md`: Improvement tracking + +## Goals + +1. **Centralize Workflow Definitions**: Maintain workflows in a single location to ensure consistency and reduce duplication +2. **Simplify Adoption**: Make it easy for any WPGraphQL repository to implement these workflows +3. **Ensure Flexibility**: Allow for repository-specific customizations while maintaining core functionality +4. **Minimize Maintenance Overhead**: Updates to workflows should propagate to all repositories without manual intervention +5. **Preserve Documentation**: Ensure that documentation remains accessible and relevant across repositories + +## Implementation Options + +### Option 1: GitHub Reusable Workflows + +GitHub Actions supports [reusable workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows), which allow workflows to be called from other workflows. + +#### Pros: +- Native GitHub feature +- Versioning support +- Clear separation between workflow definition and usage +- Simplified updates (repositories reference specific versions) + +#### Cons: +- Limited customization options +- May require refactoring existing workflows +- Inputs/outputs must be carefully defined + +### Option 2: Centralized Scripts Repository + +Create a separate repository for shared scripts, which other repositories can include as a submodule or via npm/composer. + +#### Pros: +- Maximum flexibility +- Scripts can be versioned independently +- Can be used outside of GitHub Actions + +#### Cons: +- More complex setup +- Requires additional dependency management +- May introduce synchronization challenges + +### Option 3: Hybrid Approach + +Use reusable workflows for the GitHub Actions components, and a shared package for the Node.js scripts. + +#### Pros: +- Combines benefits of both approaches +- Clear separation of concerns +- Allows for more granular versioning + +#### Cons: +- More complex architecture +- Requires maintaining two systems +- Potential for version mismatches + +## Recommended Approach: Hybrid + +The hybrid approach offers the best balance of maintainability and flexibility: + +1. **Create a `wp-graphql-workflows` Repository**: + - Contains reusable GitHub Actions workflows + - Houses shared Node.js scripts as an npm package + - Includes comprehensive documentation + +2. **Implement in Consuming Repositories**: + - Reference reusable workflows in GitHub Actions configurations + - Install shared scripts via npm/composer + - Minimal configuration required in each repository + +## Implementation Plan + +### Phase 1: Preparation (Current Repository) + +1. **Refactor Existing Workflows**: + - Identify and extract repository-specific configurations + - Create configuration templates + - Ensure all workflows can accept parameters for customization + +2. **Modularize Scripts**: + - Ensure all scripts are properly modularized (already done) + - Add configuration options for repository-specific behavior + - Create a package.json for the scripts directory + +3. **Update Documentation**: + - Document all configuration options + - Create implementation guides + - Update workflow visualizations to reflect the new architecture + +### Phase 2: Create Shared Infrastructure + +1. **Create `wp-graphql-workflows` Repository**: + - Set up repository structure + - Migrate reusable workflows + - Package scripts for distribution + - Set up versioning and releases + +2. **Create Implementation Examples**: + - Provide example configurations for different repository types + - Document common customization scenarios + - Create a quick-start guide + +### Phase 3: Implementation in Target Repositories + +1. **Implement in Core Repository**: + - Start with wp-graphql/wp-graphql + - Migrate to the shared workflows + - Document the migration process + +2. **Implement in Extension Repositories**: + - Roll out to wp-graphql-smart-cache, wpgraphql-ide, etc. + - Address any repository-specific challenges + - Refine the implementation process + +3. **Create Onboarding Documentation**: + - For new repositories + - For existing repositories without automation + - For repositories with existing automation + +## Configuration Strategy + +To make workflows truly reusable, we need a consistent configuration approach: + +### Repository Configuration File + +Each repository will include a `.wp-graphql-workflows.json` file with repository-specific settings: + +```json +{ + "name": "WPGraphQL", + "type": "plugin", + "mainFile": "wp-graphql.php", + "constantsFile": "constants.php", + "versionConstant": "WPGRAPHQL_VERSION", + "changelogFiles": [ + "CHANGELOG.md", + "readme.txt" + ], + "releaseAssets": [ + "wp-graphql.zip" + ], + "wpOrgSlug": "wp-graphql", + "buildCommand": "npm run build", + "customScripts": { + "preRelease": "npm run docs:build", + "postRelease": "npm run deploy:docs" + } +} +``` + +### Workflow Inputs + +Reusable workflows will accept inputs for customization: + +```yaml +on: + workflow_call: + inputs: + config_file: + description: 'Path to configuration file' + default: '.wp-graphql-workflows.json' + required: false + type: string + release_type: + description: 'Force a specific release type' + required: false + type: string + skip_build: + description: 'Skip build step' + required: false + type: boolean +``` + +## Script Package Structure + +The shared scripts will be packaged as `@wp-graphql/workflows`: + +``` +@wp-graphql/workflows/ +├── bin/ +│ ├── generate-changeset.js +│ ├── analyze-changesets.js +│ └── ... +├── lib/ +│ ├── utils/ +│ │ ├── changesets.js +│ │ ├── env.js +│ │ └── ... +│ ├── config.js +│ └── ... +├── package.json +└── README.md +``` + +## Timeline and Milestones + +1. **Preparation (2 weeks)** + - Refactor workflows in current repository + - Create configuration templates + - Update documentation + +2. **Infrastructure Creation (2 weeks)** + - Set up wp-graphql-workflows repository + - Package scripts + - Create implementation examples + +3. **Initial Implementation (1 week per repository)** + - wp-graphql/wp-graphql + - wp-graphql/wp-graphql-smart-cache + - wp-graphql/wpgraphql-ide + - wp-graphql/wpgraphql-acf + +4. **Refinement (Ongoing)** + - Address feedback + - Improve documentation + - Add new features + +## Success Metrics + +We'll consider this project successful when: + +1. All target repositories use the shared workflows +2. New releases can be created with minimal manual intervention +3. Workflow updates can be propagated without breaking changes +4. New repositories can adopt the workflows with minimal effort +5. Documentation is comprehensive and up-to-date + +## Next Steps + +1. Review this plan with the team +2. Begin refactoring workflows in the current repository: + - Start with `generate-changeset.yml` to make it reusable + - Create a configuration reader utility in `scripts/utils/config.js` + - Update `scripts/utils/changesets.js` to support configuration options + +3. Create a prototype of the wp-graphql-workflows repository: + - Set up basic repository structure + - Create initial package.json for the npm package + - Migrate one workflow as a proof of concept + +4. Test with a single target repository before full implementation: + - Choose wp-graphql/wp-graphql as the initial test case + - Document the migration process in detail + - Gather feedback and refine the approach + +## Repository-Specific Considerations + +### wp-graphql/wp-graphql (Core) +- Main plugin with the most complex release process +- Deploys to WordPress.org +- Has extensive documentation that needs to be updated with releases +- Uses a specific version constant (`WPGRAPHQL_VERSION`) + +### wp-graphql/wp-graphql-smart-cache +- Extension plugin with its own release cycle +- Has specific cache-related tests that need to run +- Uses a different version constant (`WPGRAPHQL_SMART_CACHE_VERSION`) + +### wp-graphql/wpgraphql-ide +- React-based application with different build process +- Not deployed to WordPress.org +- Uses semantic versioning in package.json + +### wp-graphql/wpgraphql-acf +- Extension plugin that depends on Advanced Custom Fields +- Requires specific testing with ACF +- Deploys to WordPress.org + +## Common Patterns and Differences + +### Common Patterns +- All repositories use semantic versioning +- All need changeset generation and release management +- All have some form of changelog +- All use GitHub releases + +### Key Differences +- Different version storage mechanisms (constants vs package.json) +- Different build processes +- Different deployment targets +- Different testing requirements +- Different documentation needs + +## Reference Information + +### Current Workflow Files +- `.github/workflows/generate-changeset.yml` +- `.github/workflows/release-management.yml` + +### Current Script Files +- `scripts/generate-changeset.js` +- `scripts/analyze-changesets.js` +- `scripts/generate-release-notes.js` +- `scripts/bump-version.js` +- `scripts/update-changelog.js` +- `scripts/update-readme.js` +- `scripts/update-changelogs.js` +- `scripts/update-upgrade-notice.js` + +### Current Utility Modules +- `scripts/utils/env.js` +- `scripts/utils/changesets.js` + +### Documentation Files +- `docs/WORKFLOW_VISUALIZATION.md` +- `README.md` +- `SUMMARY.md` +- `SUGGESTIONS.md` + +This plan will be updated as we progress through the implementation phases. \ No newline at end of file diff --git a/docs/WORKFLOW_VISUALIZATION.md b/docs/WORKFLOW_VISUALIZATION.md new file mode 100644 index 0000000..fcd9397 --- /dev/null +++ b/docs/WORKFLOW_VISUALIZATION.md @@ -0,0 +1,223 @@ +# Workflow Visualizations + +This document provides visual representations of the automation workflows used in this repository. These diagrams help to understand how the different components interact and the flow of operations during the release process. + +## Overall Release Process + +```mermaid +flowchart TD + PR[Pull Request] -->|Merged to develop| GC[Generate Changeset] + GC -->|Creates| CS[Changeset File] + CS -->|Accumulates in| DEV[Develop Branch] + DEV -->|PR created to main| RPR[Release PR] + RPR -->|Merged to main| RM[Release Management] + RM -->|Determines| VB[Version Bump] + RM -->|Generates| RN[Release Notes] + VB -->|Updates| VF[Version in Files] + RN -->|Updates| CL[Changelogs] + VF --> TAG[Create Tag] + CL --> TAG + TAG -->|Triggers| DEP[Deployment] + DEP -->|Creates| GHR[GitHub Release] + DEP -->|Deploys to| WP[WordPress.org] + RM -->|Syncs changes back to| DEV +``` + +## Changeset Generation Workflow + +```mermaid +flowchart TD + PR[Pull Request] -->|Merged to develop| GCW[Generate Changeset Workflow] + GCW -->|Extracts| PRM[PR Metadata] + PRM -->|Passes to| GCS[generate-changeset.js] + GCS -->|Uses| CU[changesets.js Utility] + CU -->|Creates| CSF[Changeset File] + CSF -->|Stored in| CSD[.changesets Directory] + GCW -->|Generates| RN[Release Notes] + RN -->|Checks for| EPR[Existing Release PR] + EPR -->|Yes| UPR[Update PR Body] + EPR -->|No| CPR[Create New PR] + UPR --> END[End] + CPR --> END +``` + +## Release Management Workflow + +```mermaid +flowchart TD + RPR[Release PR] -->|Merged to main| RMW[Release Management Workflow] + RMW -->|Checks out| CODE[Code] + CODE -->|Checks for| CS[Changesets] + CS -->|Yes| PARALLEL[Parallel Execution] + PARALLEL -->|Task 1| GRN[Generate Release Notes] + PARALLEL -->|Task 2| DVB[Determine Version Bump] + GRN -->|Creates| RN[Release Notes File] + DVB -->|Updates| VF[Version in Files] + RN --> UCL[Update Changelogs] + VF --> UCL + UCL -->|Commits changes to| MAIN[Main Branch] + MAIN -->|Creates| TAG[Git Tag] + TAG -->|Creates| GHR[GitHub Release] + MAIN -->|Deletes| CS + MAIN -->|Syncs back to| DEV[Develop Branch] +``` + +## Deployment Workflow + +```mermaid +flowchart TD + TAG[Git Tag] -->|Triggers| DW[Deployment Workflow] + DW -->|Checks out| CODE[Code] + CODE -->|Builds| PKG[Plugin Package] + PKG -->|Creates| ZIP[ZIP File] + ZIP -->|Uploads to| GHR[GitHub Release] + ZIP -->|Deploys to| SVN[WordPress.org SVN] + SVN -->|Available on| WP[WordPress.org] +``` + +## Script Dependencies + +```mermaid +flowchart TD + GCS[generate-changeset.js] -->|Uses| CU[changesets.js Utility] + GCS -->|Uses| EU[env.js Utility] + ACS[analyze-changesets.js] -->|Uses| CU + GRNS[generate-release-notes.js] -->|Uses| CU + GRNS -->|Uses| EU + BV[bump-version.js] -->|Uses| EU + UCL[update-changelog.js] -->|Uses| CU + UR[update-readme.js] -->|Uses| CU + UCS[update-changelogs.js] -->|Uses| UCL + UCS -->|Uses| UR + UUN[update-upgrade-notice.js] -->|Uses| CU + UUN -->|Uses| EU +``` + +## Data Flow + +```mermaid +flowchart LR + PR[PR Metadata] -->|Input to| GCS[generate-changeset.js] + GCS -->|Creates| CSF[Changeset Files] + CSF -->|Read by| GRNS[generate-release-notes.js] + CSF -->|Analyzed by| ACS[analyze-changesets.js] + ACS -->|Determines| BT[Bump Type] + BT -->|Input to| BV[bump-version.js] + GRNS -->|Generates| RN[Release Notes] + RN -->|Input to| UCL[update-changelog.js] + RN -->|Input to| UR[update-readme.js] + RN -->|Input to| UUN[update-upgrade-notice.js] +``` + +## Parallel Execution in Release Management + +```mermaid +gantt + title Release Management Workflow + dateFormat YYYY-MM-DD + section Preparation + Checkout Code :a1, 2023-01-01, 1d + Setup Node.js :a2, after a1, 1d + Install Dependencies :a3, after a2, 1d + Check for Changesets :a4, after a3, 1d + section Parallel Tasks + Generate Release Notes :b1, after a4, 2d + Determine Version Bump :b2, after a4, 2d + section Finalization + Update Changelogs :c1, after b1 b2, 1d + Commit Changes :c2, after c1, 1d + Create Tag :c3, after c2, 1d + Create GitHub Release :c4, after c3, 1d + Delete Changesets :c5, after c4, 1d + Sync to Develop :c6, after c5, 1d +``` + +## Error Handling Strategy + +```mermaid +flowchart TD + START[Start Workflow] --> CHECK[Check Inputs] + CHECK -->|Valid| EXEC[Execute Task] + CHECK -->|Invalid| ERR1[Report Error] + EXEC -->|Success| NEXT[Next Step] + EXEC -->|API Error| RATE[Check Rate Limits] + RATE -->|Limited| WARN[Log Warning] + WARN --> ALT[Try Alternative Method] + RATE -->|Not Limited| RETRY[Retry Operation] + EXEC -->|Other Error| LOG[Log Error Details] + LOG --> ALT + ALT -->|Success| NEXT + ALT -->|Failure| FALL[Use Fallback] + RETRY -->|Success| NEXT + RETRY -->|Failure| FALL + FALL -->|Success| NEXT + FALL -->|Failure| ERR2[Report Fatal Error] + ERR1 --> END[End Workflow] + ERR2 --> END + NEXT --> CLEAN[Cleanup Resources] + CLEAN --> END +``` + +## Utility Module Usage + +```mermaid +flowchart TD + subgraph "Utility Modules" + ENV[env.js] + CS[changesets.js] + end + + subgraph "Scripts" + GCS[generate-changeset.js] + ACS[analyze-changesets.js] + GRNS[generate-release-notes.js] + BV[bump-version.js] + UCL[update-changelog.js] + UR[update-readme.js] + UCS[update-changelogs.js] + UUN[update-upgrade-notice.js] + end + + ENV -->|getEnvVar| GCS + ENV -->|getEnvVar| GRNS + ENV -->|getBoolEnvVar| BV + ENV -->|getNumEnvVar| UUN + + CS -->|createChangeset| GCS + CS -->|readAllChangesets| ACS + CS -->|determineBumpType| ACS + CS -->|categorizeChangesets| ACS + CS -->|readAllChangesets| GRNS + CS -->|determineBumpType| GRNS + CS -->|categorizeChangesets| GRNS + CS -->|readAllChangesets| UCL + CS -->|readAllChangesets| UUN +``` + +## Branch Strategy + +```mermaid +gitGraph + commit id: "Initial commit" + branch develop + checkout develop + commit id: "Feature 1" + commit id: "Feature 2" + commit id: "Generate changeset for Feature 2" + commit id: "Feature 3" + commit id: "Generate changeset for Feature 3" + checkout main + merge develop + commit tag: "v1.0.0" id: "v1.0.0" + checkout develop + merge main id: "Sync v1.0.0 back to develop" + commit id: "Feature 4" + commit id: "Generate changeset for Feature 4" + checkout main + merge develop + commit tag: "v1.1.0" id: "v1.1.0" + checkout develop + merge main id: "Sync v1.1.0 back to develop" +``` + +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. \ No newline at end of file