Releasing

​

Release Strategy

• main - Active development, latest features
• v4.11 - OpenShift 4.11 compatible releases
• v4.12 - OpenShift 4.12 compatible releases
• v4.13 - OpenShift 4.13 compatible releases
• etc.

​

Prerequisites

​

GitHub Token

export GITHUB_TOKEN=<your_github_token>

• repo scope for creating releases
• write:packages scope if publishing packages

​

Install release-it

# Install globally
sudo npm install --global release-it

# Install bumper plugin locally in the repository
npm install --save-dev @release-it/bumper

​

Creating a Release

​

Release from Main

git checkout main
git pull
release-it

1. Select version: Choose patch, minor, or major version bump
2. Review changes: Confirm the changelog and version updates
3. Publish: Confirm publishing to GitHub and PyPI

​

Release from Version Branch

git checkout v4.11
git pull
release-it  # Follow the instructions

​

Semantic Versioning

​

Version Bump Guidelines

• Breaking changes to existing APIs
• Removal of deprecated features
• Major refactoring affecting compatibility

• New resource support
• New features and enhancements
• Deprecations (but not removals)

• Bug fixes
• Documentation updates
• Internal improvements

​

Examples

• 4.11.1 → 4.11.2 (patch): Bug fix release
• 4.11.2 → 4.12.0 (minor): New features added
• 4.12.5 → 5.0.0 (major): Breaking changes

​

Release Workflow

​

1. Prepare the Release

1. Ensure all tests pass:
   uv run --group tests pytest
   
2. Run pre-commit checks:
   prek run --all-files
   
3. Review merged PRs since last release:
   git log --oneline v4.11.5..HEAD
   
4. Update documentation if needed

​

2. Run release-it

release-it

• Prompt for version bump (patch/minor/major)
• Generate changelog from git commits
• Update version in pyproject.toml and other files
• Create a git tag
• Push changes and tag to GitHub
• Create a GitHub release
• Publish to PyPI (if configured)

​

3. Verify the Release

1. Check GitHub releases:
   • Visit https://github.com/RedHatQE/openshift-python-wrapper/releases
   • Verify release notes and attached assets
2. Check PyPI:
   • Visit https://pypi.org/project/openshift-python-wrapper/
   • Verify new version is published
3. Test installation:
   uv pip install openshift-python-wrapper==<new-version>
   

​

Cherry-picking to Release Branches

​

Automated Cherry-pick

1. After your PR is merged to main, add a comment:
   /cherry-pick v4.11
   
2. This creates a new PR targeting the v4.11 branch
3. Review and merge the cherry-pick PR
4. Create a patch release from the version branch:
   git checkout v4.11
   git pull
   release-it
   

​

Manual Cherry-pick

# Checkout the target branch
git checkout v4.11
git pull

# Cherry-pick the commit
git cherry-pick <commit-hash>

# Resolve conflicts if any
git add .
git cherry-pick --continue

# Push the changes
git push origin v4.11

# Create release
release-it

​

Release Configuration

{
  "git": {
    "commitMessage": "chore: release v${version}",
    "tagName": "v${version}",
    "requireCleanWorkingDir": true
  },
  "github": {
    "release": true,
    "releaseName": "Release v${version}"
  },
  "npm": {
    "publish": false
  },
  "plugins": {
    "@release-it/bumper": {
      "in": "pyproject.toml",
      "out": "pyproject.toml"
    }
  }
}

​

PyPI Publishing

​

Automated Publishing

# Ensure PyPI credentials are configured
# in ~/.pypirc or environment variables
release-it

​

Manual Publishing

# Build the distribution
uv build

# Upload to PyPI
uv publish

​

TestPyPI

# Upload to TestPyPI
uv publish --repository testpypi

# Install from TestPyPI
uv pip install --index-url https://test.pypi.org/simple/ openshift-python-wrapper

​

Post-Release Tasks

​

Update Documentation

1. Update installation docs with new version
2. Update changelog on ReadTheDocs
3. Announce release in relevant channels

​

Documentation Hosting

• Automatically builds on new releases
• Maintains docs for each version
• Serves latest stable version by default

​

Hotfix Releases

1. Create hotfix branch from version branch:
   git checkout v4.11
   git checkout -b hotfix/critical-bug
   
2. Apply the fix:
   # Make changes
   git add .
   git commit -m "fix: critical bug in resource handling"
   
3. Merge to version branch:
   git checkout v4.11
   git merge hotfix/critical-bug
   git push origin v4.11
   
4. Create patch release:
   release-it
   
5. Backport to main if needed:
   git checkout main
   git cherry-pick <commit-hash>
   git push origin main
   

​

Rollback a Release

​

Delete GitHub Release

1. Go to Releases page
2. Click on the problematic release
3. Click “Delete release”
4. Delete the corresponding git tag:
   git tag -d v4.11.6
   git push origin :refs/tags/v4.11.6
   

​

Yank from PyPI

1. Go to PyPI project page
2. Select the version
3. Click “Options” → “Yank release”
4. Provide a reason

​

Troubleshooting

​

release-it Command Not Found

sudo npm install --global release-it

​

Authentication Failed

echo $GITHUB_TOKEN
# Should output your token

# If empty, export it:
export GITHUB_TOKEN=<your_token>

​

Version Bump Failed

git status
# Should show "nothing to commit, working tree clean"

git stash  # If you have uncommitted changes

​

PyPI Upload Failed

# Check ~/.pypirc exists and is configured
cat ~/.pypirc

# Or use environment variables
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=<your-pypi-token>

​

Best Practices

1. Always release from clean working directory
2. Test thoroughly before releasing
3. Review changelog before confirming
4. Announce major releases to users
5. Maintain version branches for supported releases
6. Cherry-pick critical fixes to active version branches
7. Document breaking changes clearly
8. Use semantic versioning consistently
9. Test on TestPyPI before production release
10. Monitor issues after release for problems

​

Additional Resources

• release-it documentation
• Semantic Versioning
• PyPI Publishing Guide
• GitHub Releases