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