From fbcb22d0b0b0946a9532c582cdc7dd02d7439738 Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Thu, 20 Aug 2026 10:30:06 -0400 Subject: [PATCH 1/5] fix: install CLI as a uv tool --- Justfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Justfile b/Justfile index c9860f2..5b4a666 100644 --- a/Justfile +++ b/Justfile @@ -25,9 +25,9 @@ smoke: WHL=$(ls -t dist/*.whl | head -1) uv run --no-project --with "$WHL" posit --help -# Install the most recently built wheel into the active environment +# Install the most recently built wheel as a standalone uv tool install: build - uv pip install "$(ls -t dist/*.whl | head -1)" + uv tool install --force "$(ls -t dist/*.whl | head -1)" # Print the version that a build gets from the current git state version: From 3323845b20b4b72752c8a4f79beff6366c9b5f6b Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Thu, 20 Aug 2026 10:33:05 -0400 Subject: [PATCH 2/5] feat: add CLI uninstall recipe --- Justfile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Justfile b/Justfile index 5b4a666..327393e 100644 --- a/Justfile +++ b/Justfile @@ -29,6 +29,10 @@ smoke: install: build uv tool install --force "$(ls -t dist/*.whl | head -1)" +# Remove the installed standalone uv tool +uninstall: + uv tool uninstall posit-cli + # Print the version that a build gets from the current git state version: @uvx hatch version From 44bee02493da64e252b931768aea1044390c6d58 Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Thu, 20 Aug 2026 10:35:39 -0400 Subject: [PATCH 3/5] feat: add editable dev install recipe --- Justfile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Justfile b/Justfile index 327393e..93b6495 100644 --- a/Justfile +++ b/Justfile @@ -29,6 +29,10 @@ smoke: install: build uv tool install --force "$(ls -t dist/*.whl | head -1)" +# Install the project as an editable standalone uv tool +dev: + uv tool install --editable --force . + # Remove the installed standalone uv tool uninstall: uv tool uninstall posit-cli From 1dfc5a4f9d60be804c7f5cdfcf8df7391600cd31 Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Thu, 20 Aug 2026 10:37:23 -0400 Subject: [PATCH 4/5] feat: add dependency sync recipe --- Justfile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Justfile b/Justfile index 93b6495..f520037 100644 --- a/Justfile +++ b/Justfile @@ -1,5 +1,9 @@ # posit-cli task runner. Run `just --list` to see recipes. +# Sync project and development dependencies into the project environment +deps: + uv sync --all-extras + # Run the test suite against a single Python version (default 3.13) test py="3.13": uv run --python {{py}} --extra test pytest tests From 1b8498695b04727cf0dbc346c94884c4db63271e Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Thu, 20 Aug 2026 10:49:32 -0400 Subject: [PATCH 5/5] docs: add contributor setup guide --- CONTRIBUTING.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0500d36 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,91 @@ +# Contributing + +This guide covers local development for `posit-cli`. End-user installation and CLI usage are documented in [README.md](README.md). + +## Prerequisites + +Install these tools before starting: + +- Git +- Python 3.8 or newer +- [uv](https://docs.astral.sh/uv/) +- [just](https://github.com/casey/just) + +The project uses uv for dependency management and virtual environments. The supported Python versions are 3.8 through 3.14, which are tested in CI. + +## Set Up + +Clone the repository and change into its directory: + +```console +git clone https://github.com/posit-dev/posit-cli.git +cd posit-cli +``` + +Sync the project, test, and lint dependencies: + +```console +just deps +``` + +This runs `uv sync --all-extras`, using `uv.lock` to create or update the project environment in `.venv`. You do not need to activate `.venv` when using the `just` recipes. + +To put an editable `posit` command on your `PATH`, run: + +```console +just dev +posit --help +``` + +`just dev` installs the checkout as an editable uv tool. Changes to the source are therefore available through `posit` without rebuilding or reinstalling the package. If the command is not found, add the directory printed by `uv tool dir --bin` to your `PATH`, or run `uv tool update-shell`. + +## Common Commands + +Run these commands from the repository root: + +| Command | Purpose | +| --- | --- | +| `just deps` | Sync runtime, test, and lint dependencies from `uv.lock`. | +| `just dev` | Install the checkout as an editable uv tool. | +| `just test` | Run tests against Python 3.13. | +| `just test 3.8` | Run tests against a specific Python version. | +| `just lint` | Check formatting and run Ruff. | +| `just fmt` | Format files and apply Ruff fixes. | +| `just build` | Build the wheel and source distribution in `dist/`. | +| `just smoke` | Run `posit --help` from the latest built wheel. | +| `just install` | Install the latest built wheel as a non-editable uv tool. | +| `just uninstall` | Remove the uv-managed `posit-cli` tool. | +| `just clean` | Remove build, test, and lint artifacts. | + +`just smoke` expects a wheel to exist in `dist/`, so run `just build` first unless another command has already built one. + +## Dependency Changes + +Runtime dependencies and optional test/lint dependencies are declared in `pyproject.toml`. When changing them: + +1. Update `pyproject.toml`. +2. Run `uv lock` to update `uv.lock`. +3. Run `just deps` to sync the local environment. +4. Include both `pyproject.toml` and `uv.lock` in the change. + +CI checks that the lockfile is current with `uv lock --locked`. + +## Before Opening A Pull Request + +Run the checks relevant to your change. The normal local validation sequence is: + +```console +just deps +just lint +just test +just build +just smoke +``` + +CI also runs the test suite against Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14. Add or update tests when changing behavior, and update user-facing documentation in `README.md` when the CLI changes. + +Keep commits focused and use Conventional Commit messages, such as `fix: handle expired Connect tokens` or `docs: clarify local setup`. + +## Releases + +Release preparation and publishing are documented in [RELEASE.md](RELEASE.md). In particular, do not add a hard-coded version to `pyproject.toml`; release versions come from Git tags through `hatch-vcs`.