diff --git a/README.md b/README.md index 1cb66e4..fc55cc2 100644 --- a/README.md +++ b/README.md @@ -2,294 +2,15 @@ `ni/python-actions` is a Git repository containing reusable GitHub Actions for NI Python projects. -## Table of Contents - -- [`ni/python-actions`](#nipython-actions) - - [Table of Contents](#table-of-contents) - - [`ni/python-actions/setup-python`](#nipython-actionssetup-python) - - [Usage](#usage) - - [Inputs](#inputs) - - [`python-version`](#python-version) - - [Outputs](#outputs) - - [`python-version`](#python-version-1) - - [`python-path`](#python-path) - - [Environment Variables](#environment-variables) - - [`pythonVersion`](#pythonversion) - - [`ni/python-actions/setup-poetry`](#nipython-actionssetup-poetry) - - [Usage](#usage-1) - - [Inputs](#inputs-1) - - [`poetry-version`](#poetry-version) - - [`use-cache`](#use-cache) - - [Outputs](#outputs-1) - - [`cache-hit`](#cache-hit) - - [`ni/python-actions/check-project-version`](#nipython-actionscheck-project-version) - - [Usage](#usage-2) - - [Inputs](#inputs-2) - - [`project-directory`](#project-directory) - - [`expected-version`](#expected-version) - - [`ni/python-actions/update-project-version`](#nipython-actionsupdate-project-version) - - [Usage](#usage-3) - - [Inputs](#inputs-3) - - [`project-directory`](#project-directory-1) - - [`branch-prefix`](#branch-prefix) - - [`create-pull-request`](#create-pull-request) - - [`version-rule` and `use-dev-suffix`](#version-rule-and-use-dev-suffix) - - [`token`](#token) - -## `ni/python-actions/setup-python` - -The `setup-python` action installs Python and adds it to the PATH. - -It is a thin wrapper for https://github.com/actions/setup-python which is intended to -single-source the default Python version for multiple NI Python projects. - -By default, this action installs Python 3.11.9. - -### Usage - -```yaml -steps: -- uses: ni/python-actions/setup-python@v0.2 -``` - -### Inputs - -#### `python-version` - -You can specify the `python-version` input for testing with multiple versions of Python: - -```yaml -strategy: - matrix: - python-version: [3.9, '3.10', 3.11, 3.12, 3.13] -steps: -- uses: ni/python-actions/setup-python@v0.2 - with: - python-version: ${{ matrix.python-version }} -``` - -### Outputs - -#### `python-version` - -You can use the `python-version` output to get the actual version of Python, which is useful for caching: - -```yaml -steps: -- uses: ni/python-actions/setup-python@v0.2 - id: setup-python -- uses: actions/cache@v4 - with: - path: .venv - key: venv-${{ runner.os }}-py${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('poetry.lock') }} -``` - -`python-version` is unique across implementations (CPython vs. PyPy) and free-threaded builds: - -- CPython: "3.13.4". -- CPython with free-threading: "3.13.4t" -- PyPy: "pypy3.11.11-v7.3.19" - -#### `python-path` - -`actions/setup-python` sets the `pythonLocation` environment variable to the **directory** -containing the Python installation. - -You can also use the `python-path` output to get the path to the Python interpreter: - -```yaml -steps: -- uses: ni/python-actions/setup-python@v0.2 - id: setup-python -- run: pipx install --python ${{ steps.setup-python.outputs.python-version }} -``` - -### Environment Variables - -#### `pythonVersion` - -This is the same as `outputs.python-version` and is mainly intended for use in -`ni/python-actions/setup-poetry`. - -## `ni/python-actions/setup-poetry` - -The `setup-poetry` action installs Poetry, adds it to the PATH, and caches it to speed up -workflows. - -This action installs Poetry using the Python version that was selected by the `setup-python` -action, so you must call `setup-python` first. - -By default, this action installs Poetry 2.1.4. - -### Usage - -```yaml -steps: -- uses: ni/python-actions/setup-python@v0.2 -- uses: ni/python-actions/setup-poetry@v0.2 -- run: poetry install -v -``` - -### Inputs - -#### `poetry-version` - -```yaml -steps: -- uses: ni/python-actions/setup-python@v0.2 -- uses: ni/python-actions/setup-poetry@v0.2 - with: - poetry-version: 2.1.4 -- run: poetry install -v -``` - -#### `use-cache` - -If you run into caching problems, you can disable caching by specifying `use-cache: false`. - -### Outputs - -#### `cache-hit` - -You can use `cache-hit` to check whether Poetry was loaded from cache. This is mainly intended for -testing the action. - -## `ni/python-actions/check-project-version` - -The `check-project-version` action uses Poetry to get the version of a Python project and checks -that it matches an expected version. By default, this action checks against `github.ref_name`, which -is the GitHub release tag for GitHub release events. - -This action requires Poetry, so you must call `setup-python` and `setup-poetry` first. - -### Usage - -```yaml -steps: -- uses: ni/python-actions/setup-python@v0.2 -- uses: ni/python-actions/setup-poetry@v0.2 -- uses: ni/python-actions/check-project-version@v0.2 - if: github.event_name == 'release' -``` - -### Inputs - -#### `project-directory` - -You can specify `project-directory` to check a project located in a subdirectory. - -```yaml -- uses: ni/python-actions/check-project-version@v0.2 - with: - project-directory: packages/foo -``` - -#### `expected-version` - -You can specify `expected-version` to check against something other than `github.ref_name`. - -```yaml -- uses: ni/python-actions/check-project-version@v0.2 - with: - expected-version: ${{ steps.get-expected-version.outputs.version }} -``` - -## `ni/python-actions/update-project-version` - -The `update-project-version` action uses Poetry to update the version of a Python project and -creates a pull request to modify its `pyproject.toml` file. - -This action requires Poetry, so you must call `setup-python` and `setup-poetry` first. - -Creating a pull request requires the workflow or job to have the following `GITHUB_TOKEN` -permissions: - -```yaml -permissions: - contents: write - pull-requests: write -```` - -### Usage - -```yaml -steps: -- uses: ni/python-actions/setup-python@v0.2 -- uses: ni/python-actions/setup-poetry@v0.2 -- uses: ni/python-actions/update-project-version@v0.2 -``` - -### Inputs - -#### `project-directory` - -You can specify `project-directory` to update a project located in a subdirectory. - -```yaml -- uses: ni/python-actions/update-project-version@v0.2 - with: - project-directory: packages/foo -``` - -#### `branch-prefix` - -You can specify `branch-prefix` to customize the pull request branch names. The default value of -`users/build/` generates pull requests with names like `users/build/update-project-version-main` and -`users/build/update-project-version-releases-1.1`. - -```yaml -- uses: ni/python-actions/update-project-version@v0.2 - with: - branch-prefix: users/python-build/ -``` - -#### `create-pull-request` - -You can use `create-pull-request` and `project-directory` to update multiple projects with a single -pull request. - -```yaml -- uses: ni/python-actions/update-project-version@v0.2 - with: - project-directory: packages/foo - create-pull-request: false -- uses: ni/python-actions/update-project-version@v0.2 - with: - project-directory: packages/bar - create-pull-request: false -- uses: ni/python-actions/update-project-version@v0.2 - with: - project-directory: packages/baz - create-pull-request: true -``` - -#### `version-rule` and `use-dev-suffix` - -You can specify `version-rule` and `use-dev-suffix` to customize the versioning scheme. - -- `version-rule` specifies the rule for updating the version number. For example, `major` will - update 1.0.0 -> 2.0.0, while `patch` will update 1.0.0 -> 1.0.1. See [the docs for `poetry - version`](https://python-poetry.org/docs/cli/#version) for the list of rules and their behavior. -- `use-dev-suffix` specifies whether to use development versions like `1.0.0.dev0`. - -The defaults are `version-rule=patch` and `use-dev-suffix=true`, which have the following behavior: - -| Old Version | New Version | -| ----------- | ----------- | -| 1.0.0 | 1.0.1.dev0 | -| 1.0.1.dev0 | 1.0.1.dev1 | -| 1.0.1.dev1 | 1.0.1.dev2 | - -When you are ready to exit the "dev" phase, you should manually update the version number to the -desired release version before creating a release in GitHub. - -#### `token` - -The default GITHUB_TOKEN cannot trigger PR workflows, so the generated pull request will not run any -status checks. You can work around this by using `token` to specify a token that is saved in a -repo/org secret. - -See [Triggering further workflow -runs](https://github.com/peter-evans/create-pull-request/blob/main/docs/concepts-guidelines.md#triggering-further-workflow-runs) -in the `create-pull-request` action documentation for more info about this problem and other -solutions to it. +## Actions + +- [`ni/python-actions/setup-python`](setup-python): installs Python and adds it to the PATH, + single-sourcing the default Python version for multiple NI Python projects. +- [`ni/python-actions/setup-poetry`](setup-poetry): installs Poetry, adds it to the PATH, and caches + it to speed up workflows. +- [`ni/python-actions/check-project-version`](check-project-version): uses Poetry to get the version + of a Python project and checks that it matches an expected version. Publish workflows can use this + to verify that the release tag matches the version number in `pyproject.toml`. +- [`ni/python-actions/update-project-version`](update-project-version): uses Poetry to update the + version of a Python project and creates a pull request to modify its `pyproject.toml` file. + Publish workflows can use this to update the version in `pyproject.toml` for the next build. diff --git a/check-project-version/README.md b/check-project-version/README.md new file mode 100644 index 0000000..fde7ab7 --- /dev/null +++ b/check-project-version/README.md @@ -0,0 +1,43 @@ +# `ni/python-actions/check-project-version` + +The `ni/python-actions/check-project-version` action uses Poetry to get the version of a Python +project and checks that it matches an expected version. Publish workflows can use this to verify +that the release tag matches the version number in `pyproject.toml`. + +By default, this action checks against `github.ref_name`, which is the GitHub release tag for GitHub +release events. + +This action requires Poetry, so you must call `ni/python-actions/setup-python` and +`ni/python-actions/setup-poetry` first. + +## Usage + +```yaml +steps: +- uses: ni/python-actions/setup-python@v0.2 +- uses: ni/python-actions/setup-poetry@v0.2 +- uses: ni/python-actions/check-project-version@v0.2 + if: github.event_name == 'release' +``` + +## Inputs + +### `project-directory` + +You can specify `project-directory` to check a project located in a subdirectory. + +```yaml +- uses: ni/python-actions/check-project-version@v0.2 + with: + project-directory: packages/foo +``` + +### `expected-version` + +You can specify `expected-version` to check against something other than `github.ref_name`. + +```yaml +- uses: ni/python-actions/check-project-version@v0.2 + with: + expected-version: ${{ steps.get-expected-version.outputs.version }} +``` diff --git a/setup-poetry/README.md b/setup-poetry/README.md new file mode 100644 index 0000000..f5553b3 --- /dev/null +++ b/setup-poetry/README.md @@ -0,0 +1,42 @@ +# `ni/python-actions/setup-poetry` + +The `ni/python-actions/setup-poetry` action installs Poetry, adds it to the PATH, and caches it to +speed up workflows. + +This action installs Poetry using the Python version that was selected by the +`ni/python-actions/setup-python` action, so you must call `ni/python-actions/setup-python` first. + +By default, this action installs Poetry 2.1.4. + +## Usage + +```yaml +steps: +- uses: ni/python-actions/setup-python@v0.2 +- uses: ni/python-actions/setup-poetry@v0.2 +- run: poetry install -v +``` + +## Inputs + +### `poetry-version` + +```yaml +steps: +- uses: ni/python-actions/setup-python@v0.2 +- uses: ni/python-actions/setup-poetry@v0.2 + with: + poetry-version: 2.1.4 +- run: poetry install -v +``` + +### `use-cache` + +If you run into caching problems, you can disable caching by specifying `use-cache: false`. + +## Outputs + +### `cache-hit` + +You can use `cache-hit` to check whether Poetry was loaded from cache. This is mainly intended for +testing the action. diff --git a/setup-python/README.md b/setup-python/README.md new file mode 100644 index 0000000..5b2b0b0 --- /dev/null +++ b/setup-python/README.md @@ -0,0 +1,74 @@ +# `ni/python-actions/setup-python` + +The `ni/python-actions/setup-python` action installs Python and adds it to the PATH. + +It is a thin wrapper for https://github.com/actions/setup-python which is intended to +single-source the default Python version for multiple NI Python projects. + +By default, this action installs Python 3.11.9. + +## Usage + +```yaml +steps: +- uses: ni/python-actions/setup-python@v0.2 +``` + +## Inputs + +### `python-version` Input + +You can specify the `python-version` input for testing with multiple versions of Python: + +```yaml +strategy: + matrix: + python-version: [3.9, '3.10', 3.11, 3.12, 3.13] +steps: +- uses: ni/python-actions/setup-python@v0.2 + with: + python-version: ${{ matrix.python-version }} +``` + +## Outputs + +### `python-version` Output + +You can use the `python-version` output to get the actual version of Python, which is useful for caching: + +```yaml +steps: +- uses: ni/python-actions/setup-python@v0.2 + id: setup-python +- uses: actions/cache@v4 + with: + path: .venv + key: venv-${{ runner.os }}-py${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('poetry.lock') }} +``` + +`python-version` is unique across implementations (CPython vs. PyPy) and free-threaded builds: + +- CPython: "3.13.4". +- CPython with free-threading: "3.13.4t" +- PyPy: "pypy3.11.11-v7.3.19" + +### `python-path` + +`actions/setup-python` sets the `pythonLocation` environment variable to the **directory** +containing the Python installation. + +You can also use the `python-path` output to get the path to the Python interpreter: + +```yaml +steps: +- uses: ni/python-actions/setup-python@v0.2 + id: setup-python +- run: pipx install --python ${{ steps.setup-python.outputs.python-version }} +``` + +## Environment Variables + +### `pythonVersion` + +This is the same as `outputs.python-version` and is mainly intended for use in +`ni/python-actions/setup-poetry`. diff --git a/update-project-version/README.md b/update-project-version/README.md new file mode 100644 index 0000000..49c0b01 --- /dev/null +++ b/update-project-version/README.md @@ -0,0 +1,101 @@ +# `ni/python-actions/update-project-version` + +The `ni/python-actions/update-project-version` action uses Poetry to update the version of a Python +project and creates a pull request to modify its `pyproject.toml` file. Publish workflows can use +this to update the version in `pyproject.toml` for the next build. + +This action requires Poetry, so you must call `ni/python-actions/setup-python` and +`ni/python-actions/setup-poetry` first. + +Creating a pull request requires the workflow or job to have the following `GITHUB_TOKEN` +permissions: + +```yaml +permissions: + contents: write + pull-requests: write +```` + +## Usage + +```yaml +steps: +- uses: ni/python-actions/setup-python@v0.2 +- uses: ni/python-actions/setup-poetry@v0.2 +- uses: ni/python-actions/update-project-version@v0.2 +``` + +## Inputs + +### `project-directory` + +You can specify `project-directory` to update a project located in a subdirectory. + +```yaml +- uses: ni/python-actions/update-project-version@v0.2 + with: + project-directory: packages/foo +``` + +### `branch-prefix` + +You can specify `branch-prefix` to customize the pull request branch names. The default value of +`users/build/` generates pull requests with names like `users/build/update-project-version-main` and +`users/build/update-project-version-releases-1.1`. + +```yaml +- uses: ni/python-actions/update-project-version@v0.2 + with: + branch-prefix: users/python-build/ +``` + +### `create-pull-request` + +You can use `create-pull-request` and `project-directory` to update multiple projects with a single +pull request. + +```yaml +- uses: ni/python-actions/update-project-version@v0.2 + with: + project-directory: packages/foo + create-pull-request: false +- uses: ni/python-actions/update-project-version@v0.2 + with: + project-directory: packages/bar + create-pull-request: false +- uses: ni/python-actions/update-project-version@v0.2 + with: + project-directory: packages/baz + create-pull-request: true +``` + +### `version-rule` and `use-dev-suffix` + +You can specify `version-rule` and `use-dev-suffix` to customize the versioning scheme. + +- `version-rule` specifies the rule for updating the version number. For example, `major` will + update 1.0.0 -> 2.0.0, while `patch` will update 1.0.0 -> 1.0.1. See [the docs for `poetry + version`](https://python-poetry.org/docs/cli/#version) for the list of rules and their behavior. +- `use-dev-suffix` specifies whether to use development versions like `1.0.0.dev0`. + +The defaults are `version-rule=patch` and `use-dev-suffix=true`, which have the following behavior: + +| Old Version | New Version | +| ----------- | ----------- | +| 1.0.0 | 1.0.1.dev0 | +| 1.0.1.dev0 | 1.0.1.dev1 | +| 1.0.1.dev1 | 1.0.1.dev2 | + +When you are ready to exit the "dev" phase, you should manually update the version number to the +desired release version before creating a release in GitHub. + +### `token` + +The default GITHUB_TOKEN cannot trigger PR workflows, so the generated pull request will not run any +status checks. You can work around this by using `token` to specify a token that is saved in a +repo/org secret. + +See [Triggering further workflow +runs](https://github.com/peter-evans/create-pull-request/blob/main/docs/concepts-guidelines.md#triggering-further-workflow-runs) +in the `create-pull-request` action documentation for more info about this problem and other +solutions to it. diff --git a/update-project-version/action.yml b/update-project-version/action.yml index b309b55..f9d3b3a 100644 --- a/update-project-version/action.yml +++ b/update-project-version/action.yml @@ -77,6 +77,8 @@ runs: - name: Create pull request if: inputs.create-pull-request == 'true' uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8 + env: + action-url: https://github.com/${{ github.action_repository }}/tree/${{ github.action_ref }}/update-project-version with: base: ${{ steps.set-vars.outputs.base-branch }} branch: ${{ steps.set-vars.outputs.branch-name }} @@ -93,8 +95,8 @@ runs: ${{ steps.get-pr-details.outputs.project-table }} If the checks for this pull request appear to hang, you can work around this by closing and re-opening the PR. See - [ni/python-actions/update-project-version >> Inputs >> token](https://github.com/ni/python-actions?tab=readme-ov-file#token) and + [ni/python-actions/update-project-version >> Inputs >> token](${{ env.action-url }}#token) and [create-pull-request >> Triggering further workflow runs](https://github.com/peter-evans/create-pull-request/blob/main/docs/concepts-guidelines.md#triggering-further-workflow-runs) for more details. - This PR was generated by [ni/python-actions/update-project-version](https://github.com/ni/python-actions/). View the [workflow log](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}). + This PR was generated by [ni/python-actions/update-project-version](${{ env.action-url }}). View the [workflow log](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}).