Add PyPI publishing setup guide
- Complete setup instructions for trusted publishing - Step-by-step publishing process - Troubleshooting guide - Best practices for versioning and changelog
This commit is contained in:
Ryan Malloy
parent
d6983b76cf
commit
2aaaecf3c1
200
PYPI_PUBLISHING.md
Normal file
200
PYPI_PUBLISHING.md
Normal file
@ -0,0 +1,200 @@
|
||||
# PyPI Publishing Setup Guide
|
||||
|
||||
This guide explains how to set up and use the automated PyPI publishing workflow for the `vultr-dns-mcp` package.
|
||||
|
||||
## 🔐 Setting Up Trusted Publishing (Recommended)
|
||||
|
||||
The workflow uses [PyPI's trusted publishing](https://docs.pypi.org/trusted-publishers/) feature, which eliminates the need for API tokens. This is the most secure method.
|
||||
|
||||
### For PyPI (Production)
|
||||
|
||||
1. **Go to your project on PyPI**: https://pypi.org/manage/project/vultr-dns-mcp/
|
||||
2. **Navigate to "Publishing"** tab
|
||||
3. **Add a new trusted publisher** with these settings:
|
||||
- **PyPI Project Name**: `vultr-dns-mcp`
|
||||
- **Owner**: `rsp2k`
|
||||
- **Repository name**: `vultr-dns-mcp`
|
||||
- **Workflow filename**: `publish.yml`
|
||||
- **Environment name**: `pypi`
|
||||
|
||||
### For TestPyPI (Testing)
|
||||
|
||||
1. **Go to TestPyPI**: https://test.pypi.org/manage/project/vultr-dns-mcp/
|
||||
2. **Navigate to "Publishing"** tab
|
||||
3. **Add a new trusted publisher** with these settings:
|
||||
- **PyPI Project Name**: `vultr-dns-mcp`
|
||||
- **Owner**: `rsp2k`
|
||||
- **Repository name**: `vultr-dns-mcp`
|
||||
- **Workflow filename**: `publish.yml`
|
||||
- **Environment name**: `testpypi`
|
||||
|
||||
### GitHub Environment Setup
|
||||
|
||||
1. **Go to your repository settings**: https://github.com/rsp2k/vultr-dns-mcp/settings/environments
|
||||
2. **Create two environments**:
|
||||
- `pypi` (for production releases)
|
||||
- `testpypi` (for testing)
|
||||
3. **Optional**: Add protection rules to require manual approval for production releases
|
||||
|
||||
## 🚀 How to Publish
|
||||
|
||||
### Automatic Publishing (Recommended)
|
||||
|
||||
1. **Update the version** in `pyproject.toml`:
|
||||
```toml
|
||||
[project]
|
||||
name = "vultr-dns-mcp"
|
||||
version = "1.0.2" # Increment this
|
||||
```
|
||||
|
||||
2. **Commit your changes**:
|
||||
```bash
|
||||
git add pyproject.toml
|
||||
git commit -m "Bump version to 1.0.2"
|
||||
git push
|
||||
```
|
||||
|
||||
3. **Create and push a version tag**:
|
||||
```bash
|
||||
git tag v1.0.2
|
||||
git push origin v1.0.2
|
||||
```
|
||||
|
||||
4. **The workflow will automatically**:
|
||||
- Run all tests
|
||||
- Build the package
|
||||
- Publish to PyPI
|
||||
- Create a GitHub release
|
||||
- Test the published package
|
||||
|
||||
### Manual Publishing
|
||||
|
||||
You can also trigger publishing manually:
|
||||
|
||||
1. **Go to Actions** → **Publish to PyPI**
|
||||
2. **Click "Run workflow"**
|
||||
3. **Choose options**:
|
||||
- ✅ **Publish to TestPyPI**: Test your release first
|
||||
- ✅ **Skip if version exists**: Avoid errors for existing versions
|
||||
|
||||
## 📋 Publishing Checklist
|
||||
|
||||
Before creating a release tag:
|
||||
|
||||
- [ ] All tests are passing on the main branch
|
||||
- [ ] Version number is updated in `pyproject.toml`
|
||||
- [ ] `CHANGELOG.md` is updated with the new version
|
||||
- [ ] Documentation is up to date
|
||||
- [ ] No breaking changes without major version bump
|
||||
|
||||
## 🔄 Version Numbering
|
||||
|
||||
Follow [Semantic Versioning](https://semver.org/):
|
||||
|
||||
- **MAJOR** version: incompatible API changes (`2.0.0`)
|
||||
- **MINOR** version: new functionality, backwards compatible (`1.1.0`)
|
||||
- **PATCH** version: bug fixes, backwards compatible (`1.0.1`)
|
||||
|
||||
### Pre-release Versions
|
||||
|
||||
The workflow automatically detects pre-releases:
|
||||
- `1.0.0a1` (alpha)
|
||||
- `1.0.0b1` (beta)
|
||||
- `1.0.0rc1` (release candidate)
|
||||
- `1.0.0.dev1` (development)
|
||||
|
||||
Pre-releases are marked as "pre-release" on GitHub.
|
||||
|
||||
## 📝 Changelog Format
|
||||
|
||||
The workflow automatically extracts changelog entries. Format your `CHANGELOG.md` like this:
|
||||
|
||||
```markdown
|
||||
# Changelog
|
||||
|
||||
## [1.0.2] - 2025-01-15
|
||||
|
||||
### Added
|
||||
- New feature X
|
||||
- Support for Y
|
||||
|
||||
### Fixed
|
||||
- Bug in Z functionality
|
||||
|
||||
### Changed
|
||||
- Improved performance of A
|
||||
|
||||
## [1.0.1] - 2025-01-10
|
||||
|
||||
### Fixed
|
||||
- Critical bug fix
|
||||
```
|
||||
|
||||
## 🔧 Alternative: API Token Method
|
||||
|
||||
If you prefer using API tokens instead of trusted publishing:
|
||||
|
||||
1. **Generate API tokens**:
|
||||
- PyPI: https://pypi.org/manage/account/token/
|
||||
- TestPyPI: https://test.pypi.org/manage/account/token/
|
||||
|
||||
2. **Add secrets to repository**:
|
||||
- Go to repository **Settings** → **Secrets and variables** → **Actions**
|
||||
- Add `PYPI_API_TOKEN` and `TEST_PYPI_API_TOKEN`
|
||||
|
||||
3. **Modify the workflow** to use tokens instead of trusted publishing.
|
||||
|
||||
## 🛠️ Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"Version already exists"**:
|
||||
- PyPI doesn't allow overwriting versions
|
||||
- Increment the version number in `pyproject.toml`
|
||||
|
||||
**"Trusted publisher not configured"**:
|
||||
- Ensure you've set up trusted publishing correctly
|
||||
- Check the environment names match exactly
|
||||
|
||||
**"Tests failing"**:
|
||||
- The workflow requires all validation tests to pass
|
||||
- Fix any failing tests before tagging
|
||||
|
||||
**"Tag doesn't match version"**:
|
||||
- Ensure the git tag matches the version in `pyproject.toml`
|
||||
- Tag: `v1.0.2` should match version: `1.0.2`
|
||||
|
||||
### Manual Testing
|
||||
|
||||
Test your package locally before publishing:
|
||||
|
||||
```bash
|
||||
# Install in development mode
|
||||
pip install -e .[dev,test]
|
||||
|
||||
# Run the validation that the CI uses
|
||||
python run_tests.py --validate
|
||||
python run_tests.py --type unit
|
||||
python run_tests.py --lint
|
||||
|
||||
# Build and check the package
|
||||
python -m build
|
||||
python -m twine check dist/*
|
||||
```
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
After publishing, monitor:
|
||||
- **PyPI downloads**: https://pypistats.org/packages/vultr-dns-mcp
|
||||
- **GitHub releases**: https://github.com/rsp2k/vultr-dns-mcp/releases
|
||||
- **Actions logs**: https://github.com/rsp2k/vultr-dns-mcp/actions
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
1. Set up trusted publishing on PyPI and TestPyPI
|
||||
2. Create your first release by tagging `v1.0.1`
|
||||
3. Monitor the workflow execution
|
||||
4. Set up branch protection rules if desired
|
||||
5. Consider adding dependabot for automated dependency updates
|
||||
|
||||
The workflow is designed to be secure, robust, and easy to use. It follows Python packaging best practices and provides comprehensive validation before publishing.
|
||||
Loading…
x
Reference in New Issue
Block a user