diff --git a/README.md b/README.md index 65019dd..a8022b9 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,53 @@ # Nightly upload -This provides a standard GitHub Action to upload nightly builds to the -scientific-python nightly channel. +This is a GitHub Action that uploads nightly builds to the [scientific-python nightly channel][], +as recommended in [SPEC4 — Using and Creating Nightly Wheels][]. -In your Continuous Intregration pipeline once you've built you wheel, you can -use the following snippet to upload to our central nightly repository: +In a GitHub Actions workflow (`.github/workflows/*.yaml`), use the +following snippet to upload built wheels to the repository: ```yml jobs: steps: ... - name: Upload wheel - uses: scientific-python/upload-nightly-action@main + uses: scientific-python/upload-nightly-action@8f0394fd2aa0c85d7364a9958652e8994e06b23c # 0.1.0 with: artifacts_path: dist anaconda_nightly_upload_token: ${{secrets.UPLOAD_TOKEN}} ``` -To request access to the repository please open an issue on [this action +Note that we recommend pinning the action against a specific SHA +(rather than a tag), to guard against the unlikely event of upstream +being compromised. + +# Updating the action + +You can [use Dependabot to keep the GitHub Action up to date][], +with a `.github/dependabot.yml` config file similar to: + +```yaml +version: 2 +updates: + # Maintain dependencies for GitHub Actions + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" +``` + +# Access + +To request access to the repository, please open an issue on [this action's repository](https://github.com/scientific-python/upload-nightly-action). You can then generate a token at `https://anaconda.org/scientific-python-nightly-wheels/settings/access` -with _Allow write access to the API site_ and _Allow uploads to Standard Python repositories_ -permissions and add the token as a secret to your GitHub repository. +with permissions to _Allow write access to the API site_ and _Allow uploads to Standard Python repositories_, +and add the token as a secret to your GitHub repository. # Using nightly builds in CI -To test those nightly build, you can use the following command to install from -the nightly package. +To test against nightly builds, you can use the following command to install from +the nightly repository: ```sh python -m pip install \ @@ -37,29 +58,23 @@ python -m pip install \ matplotlib ``` -Note that `--index-url` takes priority over `--extra-index-url`. -Packages, and dependencies, with versions available on the -[nightly package index][] will be installed from there before falling back to -the [Python Package Index][PyPI] to install all remaining requested packages. - -``` -if package in nightly: - try to install from nightly -else: - try to install from pypi -``` +Note that `--index-url` takes priority over `--extra-index-url`, so +that packages, and their dependencies, with versions available in the +nightly channel will be installed before falling back to the [Python +Package Index][PyPI]. -If you want to install nightly builds within your conda environment, you can specify an -extra index in your YML file. +To install nightly builds within a conda environment, specify an extra +index in your `environment.yml`: ```yml name: test dependencies: - - pip - pip: - --pre --index-url https://pypi.anaconda.org/scientific-python-nightly-wheels/simple --extra-index-url https://pypi.org/simple - matplotlib ``` -[nightly package index]: https://anaconda.org/scientific-python-nightly-wheels +[use Dependabot to keep the GitHub Action up to date]: https://learn.scientific-python.org/development/guides/gha_basic/#updating [PyPI]: https://pypi.org/ +[scientific-python nightly channel]: https://anaconda.org/scientific-python-nightly-wheels +[SPEC4 — Using and Creating Nightly Wheels]: https://scientific-python.org/specs/spec-0004/