potier_f/ro-crate-interoperability-profile

Fork 0

mirror of https://github.com/researchobjectschema/ro-crate-interoperability-profile.git synced 2026-03-09 18:27:46 +01:00

Files

Snowwpanda 402af62f3b updating outdated publishing.md

2025-11-10 00:23:13 +01:00

7.1 KiB

Raw Blame History

Publishing Guide for lib-ro-crate-schema

This guide walks through the process of publishing this package to PyPI (Python Package Index).

Prerequisites

PyPI Account: Create accounts on both:
- Test PyPI: https://test.pypi.org/account/register/
- Production PyPI: https://pypi.org/account/register/
API Tokens: Generate API tokens for authentication:
- Test PyPI: https://test.pypi.org/manage/account/token/
- Production PyPI: https://pypi.org/manage/account/token/
Save these tokens securely - you'll use them instead of passwords.
Install Build Tools:
```
pip install --upgrade build twine
```

Pre-Publication Checklist

Before publishing, ensure:

Version number updated in pyproject.toml (follow Semantic Versioning)
README.md is up-to-date and renders correctly
All tests pass: pytest or pytest tests/
LICENSE file is present
Dependencies in pyproject.toml are correct and use appropriate version constraints
Author information is correct
Repository URLs are correct

Building the Package

Clean Previous Builds:

# Remove old build artifacts (PowerShell)
Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue

Or on Linux/Mac:

rm -rf dist/ build/ *.egg-info

Build Distribution Files:
```
python -m build
```
This creates two files in the dist/ directory:
- .tar.gz - Source distribution
- .whl - Wheel (binary distribution)

Verify the Build:

# List generated files
ls dist/

# Check package contents
tar -tzf dist/lib-ro-crate-schema-*.tar.gz

Testing on Test PyPI (Recommended First Step)

Always test your package on Test PyPI before publishing to production:

Upload to Test PyPI:
```
python -m twine upload --repository testpypi dist/*
```
When prompted:
- Username: __token__
- Password: Your Test PyPI API token (including the pypi- prefix)

Test Installation:

# Create a fresh virtual environment
python -m venv test_env
source test_env/bin/activate  # On Windows: test_env\Scripts\activate

# Install from Test PyPI
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ lib-ro-crate-schema

# Test the installation
python -c "from lib_ro_crate_schema import SchemaFacade, ro_crate_schema; print('Import successful!')"

Run Your Examples:

# Copy your examples to the test environment and run them
python examples/full_example.py
python examples/minimal_pydantic_example.py

Publishing to Production PyPI

Once you've verified everything works on Test PyPI:

Upload to PyPI:
```
python -m twine upload dist/*
```
When prompted:
- Username: __token__
- Password: Your PyPI API token (including the pypi- prefix)
Verify on PyPI:
- Visit: https://pypi.org/project/lib-ro-crate-schema/
- Check that the README renders correctly
- Verify all links work

Test Installation:

# In a fresh environment
pip install lib-ro-crate-schema
python -c "from lib_ro_crate_schema import SchemaFacade; print('Success!')"

Using GitHub Actions (Automated Publishing)

For automated publishing on release, create .github/workflows/publish.yml:

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.13'
      
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build twine
      
      - name: Build package
        run: python -m build
        working-directory: 0.2.x/lib/python/lib-ro-crate-schema
      
      - name: Publish to PyPI
        env:
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
        run: python -m twine upload dist/*
        working-directory: 0.2.x/lib/python/lib-ro-crate-schema

Then add your PyPI API token as a GitHub secret named PYPI_API_TOKEN.

Post-Publication

Tag the Release:

git tag -a v0.2.0 -m "Release version 0.2.0"
git push origin v0.2.0

Create GitHub Release:
- Go to your repository's Releases page
- Create a new release from the tag
- Add release notes describing changes
Update Documentation:
- Update any documentation that references installation
- Announce the release (if applicable)

Version Management

Follow Semantic Versioning:

MAJOR (X.0.0): Incompatible API changes
MINOR (0.X.0): Add functionality (backwards-compatible)
PATCH (0.0.X): Bug fixes (backwards-compatible)

Update version in:

pyproject.toml - version = "X.Y.Z"
src/lib_ro_crate_schema/__init__.py - __version__ = "X.Y.Z"

Troubleshooting

"File already exists" Error

You cannot upload the same version twice to PyPI
Increment the version number in pyproject.toml and rebuild

Import Errors After Installation

Check that __init__.py files properly export all public APIs
Verify package structure with: python -m pip show -f lib-ro-crate-schema

README Not Rendering

Validate Markdown: Use online tools or VS Code preview
Ensure readme = "README.md" in pyproject.toml
Check that README.md is in the same directory as pyproject.toml

Missing Dependencies

Ensure all dependencies are listed in pyproject.toml
Test in a clean virtual environment

Security Best Practices

Never commit API tokens to version control
Use API tokens instead of passwords (more secure, can be revoked)
Limit token scope to just uploads if possible
Rotate tokens periodically
Use GitHub Secrets for CI/CD automation

Resources

PyPI Help: https://pypi.org/help/
Python Packaging Guide: https://packaging.python.org/
Twine Documentation: https://twine.readthedocs.io/
Semantic Versioning: https://semver.org/

Quick Reference Commands

PowerShell:

# Clean build
Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue

# Build package
python -m build

# Upload to Test PyPI
python -m twine upload --repository testpypi dist/*

# Upload to PyPI
python -m twine upload dist/*

# Test installation
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ lib-ro-crate-schema  # Test PyPI
pip install lib-ro-crate-schema  # Production PyPI

Bash (Linux/Mac):

# Clean build
rm -rf dist/ build/ *.egg-info

# Build package
python -m build

# Upload to Test PyPI
python -m twine upload --repository testpypi dist/*

# Upload to PyPI
python -m twine upload dist/*

# Test installation
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ lib-ro-crate-schema  # Test PyPI
pip install lib-ro-crate-schema  # Production PyPI

7.1 KiB Raw Blame History