Appendix D: Upload Guide

This guide details the procedures for uploading PyEQSP distributions and documentation to their respective hosting platforms using the project’s automation suite.

Important

Protected Branch Policy: These procedures assume the main branch is protected. All changes, including version bumps, must be performed on a release branch and merged via Pull Request after verification.

Release Distribution (PyPI / TestPyPI)

To build and upload the package, use the scripts in the release/ directory. These scripts ensure that all documentation links are converted to absolute GitHub URLs for correct rendering on project pages.

1. Create Release Branch & Version Bump

Start from an up-to-date main branch and create a dedicated staging area.

git checkout main
git pull origin main
git checkout -b release_branch_1_0b1

Edit pyproject.toml to set the new version (e.g., 1.0b1).

2. Run Build with verification (TestPyPI)

From the release branch, run the pre-flight check:

python3 release/upload_release.py --testpypi

This script will:

  • Initialize the release/pypi_readme_fix.py logic to swap relative links.

  • Trigger release/build_dist.py for a clean sdist and wheel creation.

  • Verify the artifact using twine check.

  • Attempt an upload to the TestPyPI repository.

Caution

TestPyPI Immutability: If an upload to TestPyPI fails after a successful partial upload, or if you need to fix a bug discovered during the check, you must increment the version number (e.g., 1.0b1 to 1.0b2) in pyproject.toml. TestPyPI does not allow re-uploading the same version string.

3. GitHub Synchronization & CI Verification

Once the TestPyPI rendering is confirmed, push your branch and open a PR.

  1. Push Branch:

    git add .
git commit -m "Release 1.0b1: Open Beta Engagement Infrastructure"
git push -u origin release_branch_1_0b1

  2. Create Pull Request: Create a PR from your release branch to main.

  3. Verify CI: Ensure that the GitHub Actions “CI” and “Verify Distribution Build” workflows pass 100%. This serves as the final gatekeeper before the production upload.

4. Production PyPI Upload & Tagging

Once the PR is approved and merged into main:

# Switch to the updated main branch
git checkout main
git pull origin main

# Perform production upload
python3 release/upload_release.py --pypi

# Create and push the release tag
git tag release_1_0b1
git push origin release_1_0b1

Caution

PyPI Immutability & Failure Recovery: Like TestPyPI, production PyPI is strictly immutable. If the upload fails after any artifact (sdist or wheel) has been successfully accepted, you cannot re-upload to that version string. To recover:

  1. Fix the underlying issue (e.g., build error or metadata fix) on a new branch.

  2. Increment the version in pyproject.toml (e.g., 1.0b1 → 1.0b2).

  3. Restart the entire release process from Step 1.

SourceForge Documentation Mirror Upload

To update the project documentation mirror at http://pyeqsp.sourceforge.io:

1. Generate & Upload

The documentation upload is semi-automated via the release/upload_sourceforge.py script.

# This script builds the docs and generates the scp command
python3 release/upload_sourceforge.py

After reviewing the generated command, execute it to upload the doc/_build/html contents to your SourceForge htdocs directory.

2. Verify Web Rendering

Check http://pyeqsp.sourceforge.io to ensure all Markdown, mathematics symbols, and navigation elements render correctly.