solarwindpy 0.0.1.dev0__py3-none-any.whl → 0.1.0__py3-none-any.whl

plans/cicd-architecture-redesign/2-Version-Detection.md

@@ -0,0 +1,123 @@
+# Phase 2: Version Detection Configuration
+
+## Overview
+Implement intelligent version tag detection logic to differentiate between release candidates and production releases, enabling conditional deployment workflows.
+
+## Objectives
+- Configure RC vs production tag detection logic
+- Set up conditional deployment based on version type
+- Validate version detection accuracy
+- Ensure proper GitHub output variable handling
+
+## Tasks
+
+### Task 2.1: Implement Tag Detection Logic (20 minutes)
+**Implementation Steps:**
+Add this bash logic to the release-pipeline.yml workflow:
+
+```bash
+# Detect if tag is release candidate
+if [[ "$LATEST_TAG" =~ -rc[0-9]+$ ]]; then
+  echo "is_prerelease=true" >> $GITHUB_OUTPUT
+  echo "📦 Release candidate detected: $LATEST_TAG"
+else
+  echo "is_prerelease=false" >> $GITHUB_OUTPUT
+  echo "🚀 Production release detected: $LATEST_TAG"
+fi
+```
+
+**Logic Details:**
+- **Pattern**: `-rc[0-9]+$` matches release candidates (e.g., v1.0.0-rc1, v2.1.0-rc15)
+- **Output Variable**: `is_prerelease` used by subsequent steps
+- **Logging**: Clear indication of detection result
+
+### Task 2.2: Configure Deployment Gates (10 minutes)
+**Deployment Matrix:**
+
+| Component | Release Candidate | Production Release |
+|-----------|-------------------|-------------------|
+| TestPyPI | Always ✅ | Always ✅ |
+| PyPI | Never ❌ | Always ✅ |
+| Conda | Never ❌ | Always ✅ |
+| GitHub Release | Never ❌ | Always ✅ |
+
+**Conditional Logic:**
+```yaml
+# TestPyPI deployment (always runs)
+- name: Deploy to TestPyPI
+  # No condition - always runs
+
+# PyPI deployment (production only)
+- name: Deploy to PyPI
+  if: steps.detect_version.outputs.is_prerelease == 'false'
+
+# Conda deployment (production only)  
+- name: Open conda-forge issue
+  if: steps.detect_version.outputs.is_prerelease == 'false'
+
+# GitHub Release (production only)
+- name: Create GitHub Release
+  if: steps.detect_version.outputs.is_prerelease == 'false'
+```
+
+## Test Cases
+
+### Valid Release Candidate Tags
+- `v0.1.0-rc1` → `is_prerelease=true`
+- `v1.2.3-rc15` → `is_prerelease=true`
+- `v2.0.0-rc999` → `is_prerelease=true`
+
+### Valid Production Tags
+- `v0.1.0` → `is_prerelease=false`
+- `v1.2.3` → `is_prerelease=false`
+- `v10.15.20` → `is_prerelease=false`
+
+### Edge Cases
+- `v1.0.0-alpha1` → `is_prerelease=false` (not RC pattern)
+- `v1.0.0-beta2` → `is_prerelease=false` (not RC pattern)
+- `v1.0.0-rc` → `is_prerelease=false` (missing number)
+
+## Acceptance Criteria
+- [ ] Version detection regex correctly identifies RC tags
+- [ ] Production tags properly identified as non-prerelease
+- [ ] GitHub output variables set correctly
+- [ ] Deployment conditionals reference correct output variable
+- [ ] Edge cases handled appropriately
+- [ ] Logic integrated into release-pipeline.yml
+
+## Risk Mitigation
+- **Regex Validation**: Test pattern against expected tag formats
+- **Output Variables**: Ensure proper GitHub Actions variable syntax
+- **Default Behavior**: Production deployment as fallback for ambiguous cases
+- **Logging**: Clear output to debug detection issues
+
+## Progress Tracking
+- [x] Task 2.1: Tag detection logic implemented (completed in Phase 1)
+- [x] Task 2.2: Deployment gates configured (completed in Phase 1)
+- [x] Logic tested against expected tag patterns (regex validated)
+- [x] Integration with workflow completed (commit: 0c646c5)
+- [x] Ready for Phase 3: Deployment Gates
+
+## Implementation Checksum
+**Commit**: `0c646c5` - Version detection logic already implemented in release-pipeline.yml
+**Implementation Details**:
+- RC detection pattern: `-rc[0-9]+$` plus additional `-alpha`, `-beta` support
+- Output variable: `is_rc` (true for release candidates, false for production)
+- Deployment conditionals: All production-only jobs check `needs.version-analysis.outputs.is_rc == 'false'`
+
+## Phase 2 Completion Notes
+- Version detection was implemented proactively during Phase 1
+- Current implementation exceeds Phase 2 requirements by supporting alpha/beta patterns
+- All deployment gates properly configured with correct conditional logic
+- Ready to proceed directly to Phase 3 (actually just validation of existing implementation)
+
+## Time Estimate
+**Total: 30 minutes**
+- Task 2.1: 20 minutes
+- Task 2.2: 10 minutes
+
+## Notes
+- RC detection is conservative - only exact `-rc[0-9]+` pattern triggers prerelease
+- Other prerelease formats (alpha, beta) deploy to production by design
+- This ensures SolarWindPy v0.1.0-rc5 testing works correctly
+- Production deployment is the safe default for ambiguous cases

plans/cicd-architecture-redesign/3-Deployment-Gates.md

@@ -0,0 +1,169 @@
+# Phase 3: Deployment Gates Configuration
+
+## Overview
+Configure progressive deployment stages with proper validation gates to ensure safe release candidate testing and reliable production deployments.
+
+## Objectives
+- Set up TestPyPI as universal deployment target
+- Configure PyPI deployment for production releases only
+- Implement conda-forge automation for stable releases
+- Configure GitHub Release creation with proper conditions
+- Ensure proper stage sequencing and validation
+
+## Tasks
+
+### Task 3.1: Configure TestPyPI Deployment (15 minutes)
+**Purpose**: Universal deployment target for all version tags
+
+**Configuration:**
+```yaml
+- name: Deploy to TestPyPI
+  uses: pypa/gh-action-pypi-publish@release/v1
+  with:
+    repository-url: https://test.pypi.org/legacy/
+    password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+  # No condition - always runs for any version tag
+```
+
+**Benefits:**
+- Validates package building process
+- Tests deployment mechanisms
+- Safe environment for RC validation
+- No risk to production PyPI
+
+### Task 3.2: Configure PyPI Production Deployment (10 minutes)
+**Purpose**: Production deployment for stable releases only
+
+**Configuration:**
+```yaml
+- name: Deploy to PyPI
+  if: steps.detect_version.outputs.is_prerelease == 'false'
+  uses: pypa/gh-action-pypi-publish@release/v1
+  with:
+    password: ${{ secrets.PYPI_API_TOKEN }}
+```
+
+**Validation Requirements:**
+- TestPyPI deployment must succeed first
+- Version detection must identify as production release
+- PyPI secrets must be configured in repository
+
+### Task 3.3: Configure Conda-Forge Integration (5 minutes)
+**Purpose**: Automatic conda-forge PR creation for stable releases
+
+**Configuration:**
+```yaml
+- name: Open conda-forge issue
+  if: steps.detect_version.outputs.is_prerelease == 'false'
+  uses: actions/github-script@v7
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    script: |
+      github.rest.issues.create({
+        owner: 'conda-forge',
+        repo: 'solarwindpy-feedstock',
+        title: `Update solarwindpy to ${process.env.GITHUB_REF_NAME}`,
+        body: `Please update solarwindpy to version ${process.env.GITHUB_REF_NAME}\n\nPyPI: https://pypi.org/project/solarwindpy/${process.env.GITHUB_REF_NAME}/`
+      });
+```
+
+**Requirements:**
+- Only runs for production releases
+- Requires conda-forge feedstock repository to exist
+- Uses standard GitHub issue creation
+
+## Deployment Flow Sequence
+
+### Release Candidate Flow (e.g., v0.1.0-rc5)
+1. **Tag Detection** → `is_prerelease=true`
+2. **Quality Checks** → Run full test matrix
+3. **Release Branch** → Create `release/v0.1.0-rc5`
+4. **TestPyPI** → Deploy package ✅
+5. **PyPI** → Skip ❌
+6. **Conda** → Skip ❌
+7. **GitHub Release** → Skip ❌
+
+### Production Release Flow (e.g., v0.1.0)
+1. **Tag Detection** → `is_prerelease=false`
+2. **Quality Checks** → Run full test matrix
+3. **Release Branch** → Create `release/v0.1.0`
+4. **TestPyPI** → Deploy package ✅
+5. **PyPI** → Deploy package ✅
+6. **Conda** → Open feedstock issue ✅
+7. **GitHub Release** → Create release ✅
+
+## Validation Gates
+
+### Gate 1: Quality Checks
+**Requirements:**
+- All tests pass across matrix
+- Code formatting validation
+- Linting checks pass
+- Package builds successfully
+
+### Gate 2: TestPyPI Success
+**Requirements:**
+- Package uploads successfully
+- Metadata is valid
+- Dependencies resolve correctly
+- Installation test passes
+
+### Gate 3: Production Validation (Production Only)
+**Requirements:**
+- TestPyPI deployment succeeded
+- Version is not prerelease
+- PyPI secrets are available
+- No conflicts with existing versions
+
+## Acceptance Criteria
+- [ ] TestPyPI deployment configured for all version tags
+- [ ] PyPI deployment conditional on production releases
+- [ ] Conda-forge integration configured properly
+- [ ] GitHub Release creation conditional
+- [ ] Proper stage sequencing implemented
+- [ ] Validation gates enforce requirements
+- [ ] Error handling prevents partial deployments
+
+## Risk Mitigation
+- **Sequential Deployment**: TestPyPI validates before PyPI
+- **Conditional Logic**: Production deployments only when appropriate
+- **Rollback Capability**: Release branches provide recovery points
+- **Secret Management**: Proper token isolation and access control
+- **Failure Isolation**: Failures in later stages don't affect earlier ones
+
+## Progress Tracking
+- [x] Task 3.1: TestPyPI deployment configured (completed in Phase 1)
+- [x] Task 3.2: PyPI production deployment configured (completed in Phase 1)
+- [x] Task 3.3: Conda-forge integration configured (completed in Phase 1)
+- [x] Deployment flow sequence validated (progressive deployment implemented)
+- [x] Validation gates implemented (quality checks → TestPyPI → PyPI → GitHub Release)
+- [x] Ready for Phase 4: RC Testing
+
+## Implementation Checksum
+**Commit**: `0c646c5` - Deployment gates already implemented in release-pipeline.yml
+
+**Actual Implementation Details**:
+- **TestPyPI**: Always deploys, includes installation validation test
+- **PyPI**: Production only (`if: needs.version-analysis.outputs.is_rc == 'false'`)
+- **Conda-forge**: Production only, currently logs manual step (can be enhanced later)
+- **GitHub Release**: Production only with automatic release notes generation
+- **Validation**: Progressive gates with quality checks → build → TestPyPI → production stages
+
+## Phase 3 Completion Notes
+- All deployment gates implemented proactively during Phase 1
+- Implementation exceeds requirements with installation testing and release notes
+- Progressive deployment flow ensures safe RC testing and reliable production releases
+- Ready to proceed to Phase 4: Release Candidate Testing
+
+## Time Estimate
+**Total: 30 minutes**
+- Task 3.1: 15 minutes
+- Task 3.2: 10 minutes
+- Task 3.3: 5 minutes
+
+## Notes
+- Progressive deployment ensures each stage validates the next
+- Release candidates provide safe testing environment
+- Production releases get full deployment pipeline
+- Conda-forge integration automates community package updates
+- Clear separation between testing and production environments

plans/cicd-architecture-redesign/4-RC-Testing.md

@@ -0,0 +1,194 @@
+# Phase 4: Release Candidate Testing
+
+## Overview
+Test the new CI/CD workflows using v0.1.0-rc5 release candidate to validate tag detection, deployment gates, and TestPyPI integration before production deployment.
+
+## Objectives
+- Commit new workflows to master branch
+- Create and test v0.1.0-rc5 release candidate
+- Verify RC-specific deployment behavior
+- Validate TestPyPI deployment process
+- Confirm production gates remain closed
+- Document any issues for resolution
+
+## Tasks
+
+### Task 4.1: Commit New Workflows (15 minutes)
+**Implementation Steps:**
+```bash
+# Ensure workflows are ready
+ls -la .github/workflows/
+# Should show: release-pipeline.yml, continuous-integration.yml
+
+# Add and commit new workflows
+git add .github/workflows/release-pipeline.yml
+git add .github/workflows/continuous-integration.yml
+git commit -m "feat: add new CI/CD workflows with RC support
+
+- release-pipeline.yml: Progressive deployment with RC detection
+- continuous-integration.yml: Lightweight PR validation  
+- Bypasses GitHub cache corruption in legacy workflows
+- Enables v0.1.0 release to PyPI"
+
+# Push to master
+git push origin master
+```
+
+### Task 4.2: Create v0.1.0-rc5 Tag (10 minutes)
+**Implementation Steps:**
+```bash
+# Ensure on master with latest changes
+git checkout master
+git pull origin master
+
+# Create release candidate tag
+git tag -a v0.1.0-rc5 -m "Release candidate 5 for SolarWindPy v0.1.0
+
+- Test new CI/CD workflows
+- Validate TestPyPI deployment
+- Verify RC-specific behavior"
+
+# Push tag to trigger workflow
+git push origin v0.1.0-rc5
+```
+
+### Task 4.3: Monitor Workflow Execution (20 minutes)
+**Verification Checklist:**
+
+**GitHub Actions Monitoring:**
+1. Navigate to repository Actions tab
+2. Verify `release-pipeline` workflow triggered
+3. Monitor job progression:
+   - Tag detection identifies RC correctly
+   - Quality checks run across full matrix
+   - Release branch created
+   - TestPyPI deployment executes
+   - Production deployments skip
+
+**Expected Workflow Behavior:**
+```
+✅ Tag Detection: "Release candidate detected: v0.1.0-rc5"
+✅ Quality Checks: 12 jobs (3 OS × 4 Python versions)
+✅ Release Branch: Creates "release/v0.1.0-rc5"
+✅ TestPyPI: Package deployment succeeds
+❌ PyPI: Skipped (RC detected)
+❌ Conda: Skipped (RC detected)  
+❌ GitHub Release: Skipped (RC detected)
+```
+
+### Task 4.4: Validate Release Branch Creation (5 minutes)
+**Verification Steps:**
+```bash
+# Check if release branch was created
+git fetch origin
+git branch -r | grep release/v0.1.0-rc5
+
+# Should return: origin/release/v0.1.0-rc5
+
+# Inspect branch content
+git checkout release/v0.1.0-rc5
+git log --oneline -3
+# Should show recent commits leading to RC tag
+```
+
+### Task 4.5: Verify TestPyPI Deployment (10 minutes)
+**Validation Steps:**
+1. **Check TestPyPI Package Page:**
+   - Visit: https://test.pypi.org/project/solarwindpy/
+   - Confirm v0.1.0rc5 appears in version history
+   - Verify metadata and description
+
+2. **Test Installation:**
+```bash
+# Create clean test environment
+conda create -n test-rc python=3.12 -y
+conda activate test-rc
+
+# Install from TestPyPI
+pip install --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ \
+            solarwindpy==0.1.0rc5
+
+# Verify installation
+python -c "import solarwindpy; print(solarwindpy.__version__)"
+# Expected output: 0.1.0rc5
+
+# Cleanup
+conda deactivate
+conda env remove -n test-rc
+```
+
+## Success Validation
+
+### Must Succeed ✅
+- [ ] Workflows commit successfully to master
+- [ ] v0.1.0-rc5 tag creation triggers workflow
+- [ ] Version detection identifies as release candidate
+- [ ] Quality checks pass across all platforms
+- [ ] Release branch `release/v0.1.0-rc5` created
+- [ ] TestPyPI deployment completes successfully
+- [ ] Package installable from TestPyPI
+- [ ] Version number reports correctly (0.1.0rc5)
+
+### Must Skip ⚠️
+- [ ] PyPI deployment skipped (conditional logic works)
+- [ ] Conda-forge issue creation skipped
+- [ ] GitHub Release creation skipped
+- [ ] No production environment changes
+
+## Acceptance Criteria
+- [ ] New workflows operational without GitHub cache issues
+- [ ] RC detection logic working correctly
+- [ ] TestPyPI deployment pipeline functional
+- [ ] Production deployment gates properly closed
+- [ ] Release branch audit trail created
+- [ ] Package installation validates successfully
+- [ ] Ready for production release testing
+
+## Risk Mitigation
+- **Workflow Monitoring**: Real-time observation of execution
+- **Branch Protection**: Release branches preserve state for debugging
+- **TestPyPI Safety**: No impact on production PyPI
+- **Version Validation**: Confirm correct RC number format
+- **Installation Testing**: Verify package functionality
+
+## Troubleshooting
+
+### If Workflow Fails to Trigger
+- Check tag format matches `v*` pattern
+- Verify tag pushed to correct repository
+- Review GitHub Actions permissions
+
+### If Quality Checks Fail
+- Review test matrix configuration
+- Check for platform-specific issues
+- Validate conda environment setup
+
+### If TestPyPI Deployment Fails
+- Verify TEST_PYPI_API_TOKEN secret configured
+- Check package build process
+- Review upload permissions
+
+## Progress Tracking
+- [ ] Task 4.1: New workflows committed to master
+- [ ] Task 4.2: v0.1.0-rc5 tag created and pushed
+- [ ] Task 4.3: Workflow execution monitored and validated
+- [ ] Task 4.4: Release branch creation confirmed
+- [ ] Task 4.5: TestPyPI deployment verified
+- [ ] All success criteria met
+- [ ] Ready for Phase 5: TestPyPI Validation
+
+## Time Estimate
+**Total: 1 hour**
+- Task 4.1: 15 minutes
+- Task 4.2: 10 minutes  
+- Task 4.3: 20 minutes
+- Task 4.4: 5 minutes
+- Task 4.5: 10 minutes
+
+## Notes
+- This phase proves the new workflow architecture works
+- RC testing provides safe validation before production
+- TestPyPI deployment confirms packaging process
+- Release branch creation establishes audit trail
+- Success here enables confident v0.1.0 production release