|
| 1 | +# Contributing |
| 2 | + |
| 3 | +## Repository Download |
| 4 | + |
| 5 | +```sh |
| 6 | +git clone git@github.com:sandialabs/pytribeam.git |
| 7 | +``` |
| 8 | + |
| 9 | +## Virtual Environment |
| 10 | + |
| 11 | +From within the `pytribeam` directory, create a virtual environment. A virtual environment is a self-contained directory that contains a specific Python installation, along with additional packages. It allows users to create isolated environments for different projects. This ensures that dependencies and libraries do not interfere with each other. |
| 12 | + |
| 13 | +Create a virtual environment with either `pip` or `uv`. `pip` is already included with Python. `uv` must be [installed](https://docs.astral.sh/uv/getting-started/installation/). `uv` is 10 to 100 times faster than `pip`. |
| 14 | + |
| 15 | +```sh |
| 16 | +cd pytribeam |
| 17 | + |
| 18 | +# (a) pip method, or |
| 19 | +python -m venv .venv |
| 20 | + |
| 21 | +# (b) uv method |
| 22 | +uv venv |
| 23 | + |
| 24 | +# for both methods (a) and (b) |
| 25 | +source .venv/bin/activate # bash |
| 26 | +source .venv/bin/activate.fish # fish shell |
| 27 | +``` |
| 28 | + |
| 29 | +Install the code in editable form, |
| 30 | + |
| 31 | +```sh |
| 32 | +# (a) pip method, or |
| 33 | +pip install -e .[dev] |
| 34 | + |
| 35 | +# (b) uv method |
| 36 | +uv pip install -e .[dev] |
| 37 | +``` |
| 38 | + |
| 39 | +## CI/CD |
| 40 | + |
| 41 | +We separate the concerns of test, build, release, and publish throughout the `.github/workflows/` files: |
| 42 | + |
| 43 | +* [`test.yml`](/.github/workflows/test.yml) |
| 44 | +* [`release.yml`](/.github/workflows/release.yml) |
| 45 | + |
| 46 | +These YAML files cover: |
| 47 | + |
| 48 | +* **Test (Verification)** |
| 49 | + * **Purpose:** To ensure that the code is functional and hasn't introduced regressions (broken existing features). |
| 50 | + * **What happens:** Automated tools like `pytest` run your unit and integration tests. It often includes "linting" (checking code style) and type-checking. |
| 51 | + * **Key Outcome:** Confidence. If this stage fails, the process stops immediately, preventing broken code from ever reaching a user. |
| 52 | +* **Build (Packaging)** |
| 53 | + * **Purpose:** To transform your "human-readable" source code into "machine-installable" artifacts. |
| 54 | + * **What happens:** Tools (like `python -m build`) bundle your code into standard formats, such as a Wheel (`.whl`) or a Source Distribution (`.tar.gz`). |
| 55 | + * **Key Outcome:** Portability. You now have a single file (an "artifact") that contains everything needed to install your library on any compatible system. |
| 56 | +* **Release (Documentation & Tagging)** |
| 57 | + * **Purpose:** To create an official "point-in-time" snapshot of the project for project management and users. |
| 58 | + * **What happens:** A permanent Git tag (like v1.0.0) is assigned to a specific commit. A GitHub Release page is generated with a Changelog (i.e., What's New?) and the build artifacts are attached to it as "Release Assets." |
| 59 | + * **Key Outcome:** Traceability. It provides a clear history of the project's evolution and a stable place for users to download specific versions. |
| 60 | +* **Publish (Distribution)** |
| 61 | + * **Purpose:** To make the software easily available to the global ecosystem. |
| 62 | + * **What happens:** The built artifacts are uploaded to a package registry, such as PyPI (the Python Package Index). |
| 63 | + * **Key Outcome:** Accessibility. Once published, anyone in the world can install your software using a simple command like `pip install pytribeam`. |
| 64 | + |
| 65 | +Implementation details: |
| 66 | + |
| 67 | +* The reuse of `test.yml` via a `workflow_call` ensures that test logic is not duplicated. |
| 68 | +* **Dependency Chain:** `build` waits for `test`, and publish waits for both `build` and `github-release`. |
| 69 | +* **Artifact Integrity:** By building once and downing the artifacts in subsequent jobs, we ensure the exact same files go to GitHub and PyPI. |
| 70 | +* **Security:** We use `id-token: write` for PyPI's Trusted Publishing, which is a modern and secure way to handle authentication. |
| 71 | + |
| 72 | +In `release.yml` we have removed the manual `-p ${{ secrets.PYPI_TOKEN }}`. The industry standard is now [**Trusted Publishing**](https://docs.pypi.org/trusted-publishers/). You configure this in your PyPI project settings once, and GitHub Actions authenticates securely without you needing to store and rotate secrets. |
| 73 | + |
| 74 | +To configure Trusted Publishing, you tell PyPI, "Trust any code from this specific GitHub repository and workflow." This removes the need to mange long-lived API tokens or passwords in your secrets. |
| 75 | + |
| 76 | +Step: |
| 77 | + |
| 78 | +* Log into your [PyPI](https://pypi.org) account |
| 79 | +* Go your project's **Manage** page (or your accounts **Publishing** settings if you are setting it up for the first time.) |
| 80 | +* Look for the **Publishing**tab |
| 81 | +* Click **Add new publisher** |
| 82 | +* Select **GitHub** as the source |
| 83 | +* Enter the following details: |
| 84 | + * Owner: sandialabs |
| 85 | + * Repository name: pytribeam |
| 86 | + * Workflow name: `release.yml` (This must match your filename in your `.github/workflows/` directory)) |
| 87 | + * Environment name: You can leave this blank or name it `pypi` (if you use it in your YAML). We used `pypi`. |
| 88 | + * Click the **Add** button |
| 89 | + |
| 90 | +To create a release: |
| 91 | + |
| 92 | +* Merge the `dev` branch into the `main` branch. |
| 93 | +* On the `main` branch, `git tag` and push to `main`, e.g., |
| 94 | + |
| 95 | +```sh |
| 96 | +# Ensure you are on the main branch |
| 97 | +git checkout main |
| 98 | +git pull |
| 99 | + |
| 100 | +# View existing tags, if any |
| 101 | +git tag |
| 102 | + |
| 103 | +# Create the new tag, e.g., |
| 104 | +git tag -a v1.0.0 -m "Release version 1.0.0" |
| 105 | + |
| 106 | +# On the main branch, push the tag to GitHub |
| 107 | +git push origin v1.0.0 |
| 108 | +``` |
0 commit comments