Add GitHub Actions based CI workflow to build the project

[matthewfeickert]

In a PR add a GitHub Actions based workflow to the project that:

• builds an sdist and a wheel for the project on a ubuntu-latest runner
• also builds a wheel on macos-latest, and windows-latest runners
• Uses additional GitHub Actions to upload the sdist and wheels to GitHub as run artifacts.

To get started, read through the GitHub Actions: Intro guide that @henryiii wrote for Scientific Python and ask any questions that you have in this Issue. :+1:

We'll just start with doing a simple build here (e.g. python -m build .), and then move to using cibuildwheel in a follow up PR.

[matthewfeickert]

BTW, it is fine to open a PR in "draft" mode before you're ready to merge it or have someone review it. This is usually where most of the post-planning and implementation focused discussions happen on GitHub.

[j-s-ashley]

I'm sure I'll be making use of "draft" mode! 😆 I'm currently stuck on trying to get the workflow to use the python build module. The guide uses pipx, which seems to be integrated into GH Actions.

So far, I've attempted to get each OS to set up Python 3.11 and run python -m pip install build, which seems to work, but the workflow still fails when it's time to use the module.

[henryiii]

You don't need to upload the wheels anywhere, binary wheels are not guaranteed to work anywhere except the machine they were built on unless you use cibuildwheel. (Windows pretty much should work, but macOS will require a very recent macOS and Linux won't work at all without the extra steps that cibuildwheel will do for you).

I'd recommend pipx run build --sdist generally. Where's the workflow for the image above?

- uses: actions/checkout@v4
- uses: actions/setup-python@v5
  with:
    python-version: "3.12"
- run: python -m pip install build
- run: python -m build .

Should always have a build module.

[j-s-ashley]

Where's the workflow for the image above?

This is the workflow.

[henryiii]

Ah, yes, jobs are separate. Steps run in a job. Each job is an unrelated VM instance.

[henryiii]

If you want to communicate between jobs (needs:), you have to use upload-artifact / download-artifact to send files. They don't share anything else.

[j-s-ashley]

Can you do that with something like an installed package?

[henryiii]

You can do it with wheels and SDists, not with the installed environments.

Trying to find an example, lots of my packages now use hynek/build-and-inspect-python-package@v2, which is a composite action, meaning it contains 4-5 steps which include the build step and the artifact upload step.

[henryiii]

Here's one of my older ones where you can see files being transferred between jobs:

https://github.com/scikit-build/scikit-build/blob/main/.github/workflows/cd.yml

You can also download the artifacts from the job for some period of time.

I've asked Copilot to explain it:

Certainly! This GitHub Actions workflow is designed to automate continuous deployment (CD) tasks. Let's break it down: 1. **Workflow Name**: The workflow is named "CD." 2. **Triggers**: - `workflow_dispatch`: Allows manual triggering of the workflow. - `release`: Triggers the workflow when a release is created. 3. **Jobs**: - `dist`: This job runs on an `ubuntu-latest` runner. - Steps: 1. `actions/checkout@v4`: Checks out the repository code. 2. `pipx run build`: Builds an SDist and wheel (Python package distribution formats). 3. `actions/upload-artifact@v4`: Uploads the built artifacts (dist/*) as an artifact. 4. `pipx run twine check dist/*`: Checks metadata using Twine (a Python package publishing tool). - `publish`: This job depends on the successful completion of the `dist` job. - Environment: `pypi` - Permissions: Grants write access to an ID token. - Runs on an `ubuntu-latest` runner. - Condition: Executes only if the event is a published release. - Steps: 1. `actions/download-artifact@v4`: Downloads the artifact created in the `dist` job. 2. `pypa/gh-action-pypi-publish@release/v1`: Publishes the artifact to PyPI (Python Package Index). In summary, this workflow builds Python packages, checks their metadata, and publishes them to PyPI when a release is created. [You can find more information about GitHub Actions workflows in the ](https://docs.github.com/en/actions/using-workflows/about-workflows)[[official documentation](https://docs.github.com/en/actions/using-workflows/about-workflows)](https://docs.github.com/en/actions/using-workflows/about-workflows) ¹.²³⁴. Is there anything else you'd like to know? 😊 Source: Conversation with Copilot, 5/24/2024 ([1](https://docs.github.com/en/actions/using-workflows/about-workflows)) About workflows - GitHub Docs[.](https://docs.github.com/en/actions/using-workflows/about-workflows) https://docs.github.com/en/actions/using-workflows/about-workflows. ([2](https://resources.github.com/learn/pathways/automation/essentials/building-a-workflow-with-github-actions/)) Building a CI/CD Workflow with GitHub Actions | GitHub Resources. https://resources.github.com/learn/pathways/automation/essentials/building-a-workflow-with-github-actions/. ([3](https://docs.github.com/en/actions/quickstart)) Quickstart for GitHub Actions - GitHub Docs. https://docs.github.com/en/actions/quickstart. ([4](https://blog.devops.dev/a-complete-guide-to-creating-github-actions-pipeline-with-yaml-templates-c57f2dbc2d0c)) A Complete Guide to Creating GitHub Actions Pipeline with YAML .... https://blog.devops.dev/a-complete-guide-to-creating-github-actions-pipeline-with-yaml-templates-c57f2dbc2d0c.

[matthewfeickert]

You don't need to upload the wheels anywhere, binary wheels are not guaranteed to work anywhere except the machine they were built on unless you use cibuildwheel.

Yeah, the point here was just to get familiar with the idea of uploading build artifacts, but it is a good point that this can be done just via uploading the sdist and the wheel uploads can be ignored.