release: next version 📦

.changesets/20250317T225453-pr-4.md

@@ -0,0 +1,9 @@
+---
+title: "feat: test  tag updates"
+pr: 4
+author: "jasonbahl"
+type: "feat"
+breaking: false
+description: |
+  null
+---

.github/workflows/UPDATE_SINCE_TAGS.md

@@ -0,0 +1,100 @@
+# @since Tag Update Implementation Plan
+
+## Overview
+
+This document outlines the plan for implementing automated `@since` tag updates during the release process. The system will update placeholder version tags (such as `@since todo`, `@since next-version`, and `@since tbd`) with the actual version number during releases.
+
+## Implementation Checklist
+
+### 1. Package.json Updates ✅
+- [x] Add `chalk` to devDependencies
+- [x] Add a new npm script for running the update-since-tags.js (e.g., `since-tags:update`)
+
+### 2. Script Enhancements (update-since-tags.js) ✅
+- [x] Add better console output formatting using chalk
+- [x] Enhance logging to provide detailed information about updated files
+- [x] Add functionality to generate a summary of updates for release notes
+- [x] Add documentation for supported placeholders (`todo`, `next-version`, `tbd`)
+- [x] Add error handling for file operations
+- [x] Add validation for version number input
+
+### 3. Testing ✅
+- [x] Test script locally with various scenarios
+- [x] Test with multiple @since tags in single file
+- [x] Test with no @since tags present
+- [ ] Test workflow with actual PR and release
+- [ ] Test error scenarios in workflow context
+
+### 4. Release Management Workflow Updates (Next Steps) 🚀
+- [x] Add new step in release-management.yml after version bump
+- [x] Integrate since-tag updates into the workflow
+- [x] Add logging output to release notes
+- [x] Handle potential errors gracefully
+- [x] Ensure changes are committed with version bump
+
+### 5. Changeset Integration
+- [ ] Modify generate-changeset.yml to detect files with @since placeholders
+- [ ] Add @since placeholder information to changeset content
+- [ ] Update release PR template to include @since placeholder information
+- [ ] Ensure this information flows through to final release notes
+
+### 6. Documentation Updates
+- [ ] Update SUMMARY.md with new functionality
+- [ ] Update main README.md with @since tag information
+- [ ] Update workflow documentation
+- [ ] Add examples of using @since placeholders
+- [ ] Document supported file types (PHP only for now)
+
+## Script Enhancements Completed ✅
+
+The `update-since-tags.js` script has been enhanced with:
+- Improved console output using chalk for better readability
+- Detailed logging of file updates and error conditions
+- Release notes summary generation
+- Version number validation
+- Error handling for file operations
+- Support for counting and reporting the number of updates per file
+- Temporary file creation for workflow integration
+
+## Local Testing Results ✅
+
+The script has been successfully tested locally with:
+- Multiple files containing @since placeholders
+- Files with multiple placeholders
+- Files with no placeholders
+- Proper version number validation
+- Summary generation for release notes
+- Colored console output for better readability
+
+## Supported Placeholders
+
+The following placeholders will be automatically updated during release:
+- `@since todo`
+- `@since next-version`
+- `@since tbd`
+
+## File Types
+
+Currently, the system only scans PHP files for @since placeholders. This may be expanded in future versions.
+
+## Notes
+
+- The script currently works as-is with CommonJS modules
+- We're focusing on PHP files only for the initial implementation
+- Changes are being made incrementally to avoid disrupting existing workflows
+- Each change is tested thoroughly before moving to the next item
+
+## Next Steps 🚀
+
+1. Integrate the script into release-management.yml workflow
+2. Test the integration with a real PR and release
+3. Implement changeset integration for @since placeholder tracking
+4. Update all documentation
+
+## Future Considerations
+
+- Support for additional file types (js, jsx, tsx, etc.)
+- Support for additional placeholder formats
+- Integration with other documentation tools
+- Automated testing for the script
+- Performance optimization for large codebases 

.github/workflows/release-management.yml

@@ -92,6 +92,31 @@ jobs:
           NEW_VERSION=$(grep -oP "define\('AUTOMATION_TESTS_VERSION', '\K[^']+" constants.php)
           echo "version=${NEW_VERSION}" >> $GITHUB_OUTPUT
 
+      - name: Update @since tags
+        id: update_since_tags
+        run: |
+          # Run the since-tags update script with the new version
+          npm run since-tags:update -- ${{ steps.version_bump.outputs.version }}
+
+          # Check if summary file exists and has content
+          if [ -f "/tmp/since-tags-summary.md" ]; then
+            # Read the summary file
+            SINCE_SUMMARY=$(cat /tmp/since-tags-summary.md)
+
+            # Properly escape the content for GitHub Actions
+            SINCE_SUMMARY="${SINCE_SUMMARY//'%'/'%25'}"
+            SINCE_SUMMARY="${SINCE_SUMMARY//$'\n'/'%0A'}"
+            SINCE_SUMMARY="${SINCE_SUMMARY//$'\r'/'%0D'}"
+
+            # Set the output
+            echo "has_updates=true" >> $GITHUB_OUTPUT
+            echo "summary<<EOF" >> $GITHUB_OUTPUT
+            echo "$SINCE_SUMMARY" >> $GITHUB_OUTPUT
+            echo "EOF" >> $GITHUB_OUTPUT
+          else
+            echo "has_updates=false" >> $GITHUB_OUTPUT
+          fi
+
       - name: Update changelogs
         run: |
           # First, check if this is a breaking change release by using our new script
@@ -125,6 +150,12 @@ jobs:
             npm run release:notes 2>/dev/null | grep -v "^>" > /tmp/release-notes/release_notes.md
           fi
 
+          # Check if we have @since tag updates to append
+          if [[ "${{ steps.update_since_tags.outputs.has_updates }}" == "true" ]]; then
+            echo "" >> /tmp/release-notes/release_notes.md
+            echo "${{ steps.update_since_tags.outputs.summary }}" >> /tmp/release-notes/release_notes.md
+          fi
+
           # Check if the file has content
           if [ ! -s /tmp/release-notes/release_notes.md ]; then
             # If empty, provide a default message

automation-tests.php

@@ -19,4 +19,13 @@
 
 // New Feature 1
 
+/**
+ * Testing a new feature with a since tag
+ * 
+ * @since next-version
+ * @deprecated @since next-version This function was deprecated when it was added because it was just a test.
+ */
+function test_since_next_version() {
+  _deprecated_function( 'test_since_next_version', '@since next-version', '' )
+}
 

package.json

@@ -14,7 +14,8 @@
     "build": "node scripts/build.js",
     "release:prepare": "npm run version:bump && npm run changelogs:update",
     "test": "echo \"Error: no test specified\" && exit 1",
-    "upgrade-notice:update": "node scripts/update-upgrade-notice.js"
+    "upgrade-notice:update": "node scripts/update-upgrade-notice.js",
+    "since-tags:update": "node scripts/update-since-tags.js"
   },
   "repository": {
     "type": "git",
@@ -35,6 +36,7 @@
   "homepage": "https://github.com/jasonbahl/automation-tests#readme",
   "devDependencies": {
     "archiver": "^5.3.1",
+    "chalk": "^4.1.2",
     "dotenv": "^16.4.7",
     "fs-extra": "^11.1.1",
     "glob": "^10.3.3",