Developers Manual

1 Developer Guide: Releasing Cloudmesh CMA

This document outlines the workflow for building, validating, and publishing new versions of cloudmesh-cma.

1.1 1. Prerequisites

Before attempting a release, ensure you have:

  • An account and API Token for TestPyPI.
  • An account and API Token for PyPI.
  • The build and twine packages installed:
  pip install --upgrade build twine

1.2 2. Versioning

To avoid synchronization errors, we use a single version number at

  • cma_shell/__init__.py.

Instead of opening files manually to change the version, use the following commands to suggest a new version say

make version
  • Update to a new version: Decide upon your new number. Let us assume it is 4.0.1.dev1. Now update it in the file with:

make patch V=4.0.1.dev1

1.2.1 The Appendix Strategy (.devN)

CRITICAL: PyPI and TestPyPI are immutable. You cannot overwrite a version once uploaded.

  1. Testing: Set version to a development suffix (e.g., 4.0.1.dev1).
  2. Verification: Upload and install from TestPyPI.
  3. Production: Once verified, remove the suffix (e.g., 4.0.1) and upload to the real PyPI.

1.3 3. The Release Workflow

The Makefile automates the chain of dependencies. Each step ensures the previous one succeeded.

1.3.1 Step A: Build and Validate

make version             # suggest a new version
make patch V=4.0.1.dev1  # Set your test version
make check               # clean -> build -> twine check
  • Success: Should see PASSED for both the wheel and source distribution.

1.3.2 Step B: Upload to TestPyPI (The Sandbox)

Test your .dev version here first to ensure the README renders and the package is intact.

make test-upload

Make sure you have a token from pypi and store it in ~/.pypirc as discussed at the end of this file. Otherwise the upload will not work. See https://pypi.org/help/

1.3.3 Step C: Verify the Test Install

This uninstalls your local copy and pulls the package from the cloud to ensure all dependencies and entry points work.

make test-install
  • Note: The Makefile uses the --pre flag, which is required for pip to find .dev versions.

1.3.4 Step D: Promote to Production (The Real PyPI)

Only proceed once Step C is successful.

  1. Modify Version:
    make patch V=4.0.1
  1. Upload:
    make upload

  1. Final Warning on Immutability: > [!CAUTION]

    Once 4.0.1 is uploaded to the real PyPI, it is permanent. If you find a bug 5 minutes later, you must increment to 4.0.2.dev1 or 4.0.2 using make patch to upload again.

1.3.5 Step E: Git Tagging

After a successful production upload, create a permanent snapshot in your Git history.

make tag

This extracts the version from your code, creates a git tag (e.g., v4.0.1), and pushes it to the remote repository.

1.4 4. Troubleshooting

Error Cause Solution
400 Bad Request Version already exists Increment version using make patch V=....
403 Forbidden Invalid Token You likely swapped your Test and Production tokens.
Long Description Missing Missing README link Ensure readme = "README.md" is in pyproject.toml.
Package Not Found Missing --pre flag If installing a .dev version, you must use pip install --pre.

Export to Sheets

1.5 5. Automation Tip

To avoid typing tokens manually, create a ~/.pypirc file:

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
  username = __token__
  password = pypi-YOUR-PROD-TOKEN

[testpypi]
  repository = https://test.pypi.org/legacy/
  username = __token__
  password = pypi-YOUR-TEST-TOKEN

IMPORTANT: Secure this file with chmod 600 ~/.pypirc.