Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 26 additions & 22 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,11 @@ policies contributions follow. How the service works, and how it is developed, t

## 🚧 Getting Started

We encourage developers to work on their own forks of the repository. This allows you to work on features or fixes
without affecting the main codebase until your changes are ready to be merged.
Contributors work in this repository itself: clone it, push your work to a branch of your own, and open a pull request
from that branch. Your changes stay out of `dev` until they are reviewed and merged. Forks are not accepted.

To push branches here, you need write access to the repository. Ask the maintainers in the `#pesu-auth` channel on
PESU Discord to add you to the developer team.

### 🌐 Deployment Environment

Expand All @@ -42,32 +45,32 @@ We maintain two deployment environments:
- **Production**: https://pesuauth.onrender.com - [Status Page](https://xzlk85cp.status.cron-job.org/)

Merges to `dev` deploy to staging automatically. Production is deployed manually by maintainers, after the change has
been validated on staging. How both pipelines work is described in [docs/deployment.md](../docs/deployment.md).
been validated on staging. Every pull request also gets its own preview at
`https://pesuauth-dev-pr-<number>.onrender.com` while it is open; it runs unreviewed code, so never sign in to it with
your own PESU Academy credentials. How all of this works is described in [docs/deployment.md](../docs/deployment.md).

### πŸ”„ Development Workflow

The standard workflow for contributing is as follows:

1. Fork the repository on GitHub and clone it to your local machine with `--recurse-submodules` (see
[Coding Agents](#-coding-agents)).
1. Create a new branch for your feature or bug fix.
1. Clone the repository to your local machine with `--recurse-submodules` (see [Coding Agents](#-coding-agents)).
1. Create a new branch for your feature or bug fix from the latest `dev`.
1. Make your changes and commit them with clear, descriptive messages.
1. Push your branch to your fork on GitHub.
1. Create a Pull Request (PR) against the repository's `dev` branch (not `main`).
1. Push your branch to the repository.
1. Create a Pull Request (PR) from your branch against the `dev` branch (not `main`).
1. Wait for review and feedback from the maintainers, address any comments or suggestions.
1. Once approved, your changes will be merged into the `dev` branch and deployed to staging for testing.
1. Once merged into `dev` and CI passes, deployment to staging is triggered automatically.
1. Production deployment is performed manually by authorized maintainers after successful staging validation.

> [!WARNING]
> Please note that you will not be able to push directly to either the `dev` or `main` branches of the repository. All
> PRs
> must be raised from a feature branch of your forked repository and target the `dev` branch. Direct PRs to `main` will be
> closed.
> PRs must be raised from your own feature branch in this repository and target the `dev` branch. CI fails PRs from a
> fork, from `dev` or `main`, or to any branch other than `dev`. Only push to your own branches.

## πŸ› οΈ Development Environment Setup

You need Python 3.14 or higher, [`uv`](https://docs.astral.sh/uv/), Git and Docker. In a clone of your fork:
You need Python 3.14 or higher, [`uv`](https://docs.astral.sh/uv/), Git and Docker. In your clone of the repository:

```bash
uv sync --all-groups
Expand All @@ -86,8 +89,8 @@ with `--recurse-submodules`.

- Do not edit `AGENTS.md` or `.agents/` here: open a pull request against pesu-dev/skills instead.
- Do not edit `.github/agents/` by hand: it is generated from the roles by `uv run python scripts/sync_agents.py`.
- Hand an issue to Copilot's cloud agent on **your fork**, not here, since pull requests to pesu-dev/auth must come from
a fork.
- To hand an issue to Copilot's cloud agent, assign it here. Copilot opens its pull request from a branch of this
repository, and a maintainer may need to approve its workflow runs.

How the submodule, the generated agents and Dependabot's submodule updates work is described in
[docs/development.md](../docs/development.md#coding-agents).
Expand All @@ -99,8 +102,8 @@ How the submodule, the generated agents and Dependabot's submodule updates work
- Add tests with every feature and bug fix. Coverage is measured over every Python file outside `tests/`, counting
branches, and the gate is **100%**.
- Never let a unit test reach PESU Academy; use the fixtures in `tests/unit/conftest.py`.
- Run the live tests locally before you open a pull request. GitHub withholds secrets from fork pull requests, so CI
only runs them once the change reaches `dev`.
- CI runs the live tests on every pull request. If you have a PESU Academy account to test with, run them locally too
before you push a change to how the service talks to PESU Academy.
- Every live test run and benchmark makes real logins to PESU Academy: run them when you need them, not in a loop, and
never alongside each other.

Expand All @@ -112,14 +115,15 @@ How to run the tests, the live tests and the benchmarks, and how to write tests,

### πŸ”€ Create a Branch

Start by creating a new branch for your work:
Start by creating a new branch for your work from the latest `dev`:

```bash
git checkout -b your-feature-name
git fetch origin
git switch -c your-feature-name origin/dev
```

Replace `your-feature-name` with a descriptive name related to the change (e.g., `fix-token-expiry-bug` or
`docs-update-readme`).
Replace `your-feature-name` with a descriptive name related to the change (e.g., `fix/token-expiry-bug` or
`docs/update-readme`). Everyone pushes branches to the same repository, so pick a name nobody else is using.

### ✏️ Make and Commit Changes

Expand Down Expand Up @@ -159,10 +163,10 @@ does not reset the numbers to its right, such as `4.19.1`.

### πŸ“€ Push and Open a Pull Request

1. Push your branch to your fork:
1. Push your branch to the repository:

```bash
git push origin your-feature-name
git push -u origin your-feature-name
```

1. Open a Pull Request (PR) on GitHub targeting the `dev` branch.
Expand Down
2 changes: 1 addition & 1 deletion .github/agents/release-manager.agent.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: release-manager
description: Prepares a finished pesu-auth change for review - bumps the version once, shapes Conventional Commits, pushes to the contributor's fork and opens the PR to pesu-dev/auth dev with the template filled in truthfully. Never merges or deploys.
description: Prepares a finished pesu-auth change for review - bumps the version once, shapes Conventional Commits, pushes the branch to pesu-dev/auth and opens the PR to dev with the template filled in truthfully. Never merges or deploys.
---

<!-- Generated from .agents/pesudev-skills/auth/agents/release-manager.md by `uv run python scripts/sync_agents.py`. Do not edit. -->
Expand Down
21 changes: 15 additions & 6 deletions .github/workflows/ci_checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,11 @@ concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: false

# Pull requests come from branches of this repository and run their own, unreviewed code here, so the token
# stays read-only; the repository's default would let that code write to the repository.
permissions:
contents: read

jobs:
pr_source_checker:
name: PR source checker
Expand Down Expand Up @@ -45,14 +50,13 @@ jobs:
echo " - Target repo: $TARGET_REPO"
echo " - Target branch: $TARGET_BRANCH"

if [ "$SOURCE_REPO" = "$TARGET_REPO" ]; then
echo "ℹ️ Pull request originates from this repository ($SOURCE_REPO)."
else
echo "ℹ️ Pull request originates from fork ($SOURCE_REPO)."
if [ "$SOURCE_REPO" != "$TARGET_REPO" ]; then
echo "❌ PR comes from the fork $SOURCE_REPO. Forks are not accepted: push your branch to $TARGET_REPO and open the PR from there. Pushing needs write access; .github/CONTRIBUTING.md says how to get it."
exit 1
fi

if [ "$SOURCE_BRANCH" = "main" ]; then
echo "❌ PR cannot come from the 'main' branch."
if [ "$SOURCE_BRANCH" = "dev" ] || [ "$SOURCE_BRANCH" = "main" ]; then
echo "❌ PR cannot come from the '$SOURCE_BRANCH' branch. Create a branch for your change."
exit 1
fi

Expand Down Expand Up @@ -137,6 +141,11 @@ jobs:
name: Build image on PR
needs: [pr_source_checker]
if: github.event_name == 'pull_request'
# The reusable workflow's job asks for packages: write (it can push), and a called job cannot get more than its
# caller grants. With push: false nothing is published.
permissions:
contents: read
packages: write
uses: pesu-dev/actions/.github/workflows/build_push_image.yml@v1
with:
image_name: pesu-auth
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/copilot-setup-steps.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ name: Copilot Setup Steps
on:
workflow_dispatch:
push:
branches:
- dev
paths:
- .github/workflows/copilot-setup-steps.yml
pull_request:
Expand Down
8 changes: 8 additions & 0 deletions docs/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,14 @@ Both deploy workflows only run on `dev`, so always pick `dev` when starting one
Every merge to `dev` is deployed to staging automatically, once CI passes. If newer commits have landed on `dev` in the
meantime, only the newest one is deployed. You can also deploy the latest `dev` by hand.

## Pull request previews

Render deploys every pull request to its own preview, `https://pesuauth-dev-pr-<number>.onrender.com`, and removes it
when the pull request is closed or merged. A preview is a copy of the staging service running the pull request's code,
with staging's environment variables, so its `/health` reports `staging`. It runs code nobody has reviewed yet: use it
to check a change, never as an API to depend on, and never sign in to it with your own PESU Academy credentials, since
the pull request's code could log them.

## Production

Maintainers release to production by hand. A release always deploys the latest commit on `dev`:
Expand Down
36 changes: 24 additions & 12 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,11 +80,22 @@ locations agents read.
Clone with the submodule, or the links point at nothing and agents see no instructions:

```bash
git clone --recurse-submodules https://github.com/<your-username>/auth.git
git clone --recurse-submodules https://github.com/pesu-dev/auth.git
# already cloned without it:
git submodule update --init
```

A clone made from a fork, before pull requests moved to branches of this repository, has the fork as `origin` and this
repository as `upstream`. Point `origin` at this repository instead:

```bash
git remote rename origin fork && git remote rename upstream origin
git fetch origin && git branch -u origin/dev dev
```

If the clone has no `upstream` remote, run `git remote add origin https://github.com/pesu-dev/auth.git` instead of the
second rename.

On Windows, turn on Developer Mode and run `git config --global core.symlinks true` before cloning,
so the links are checked out as links.

Expand All @@ -102,13 +113,15 @@ regenerate them and commit the result:
uv run python scripts/sync_agents.py
```

Dependabot's submodule pull requests cannot do that themselves. If one fails `sync-agents`, open a
pull request from your fork that bumps the submodule to the same commit and regenerates the agents
(with the usual version bump); Dependabot then closes its own.
Dependabot's submodule pull requests cannot do that themselves. If one fails `sync-agents`, a
maintainer can push the regenerated agents and a version bump to Dependabot's branch (the Version
check skips only the runs Dependabot itself triggers, so it checks that push), or anyone can open a
pull request from a new branch that bumps the submodule to the same commit and regenerates the
agents (with the usual version bump); Dependabot then closes its own.

To hand an issue to Copilot's cloud agent, assign it on **your fork**, not here: the agent opens its
pull request in the repository it runs in, and pull requests to pesu-dev/auth must come from a fork.
Open the pull request from your fork to `dev` yourself once Copilot's is ready.
To hand an issue to Copilot's cloud agent, assign it here: the agent opens its pull request from a
`copilot/` branch of this repository, which is a pull request like any other. A maintainer may need
to approve its workflow runs before CI starts.

## Code quality

Expand Down Expand Up @@ -140,15 +153,14 @@ CI runs the same hooks in the `Pre-commit hooks` job, except `pytest`, because t
A few checks require the PR itself or Docker and cannot be run as pre-commit hooks. Here is how to run each one
locally:

- **PR source checker:** verifies the PR does not come from the `main` branch and targets `dev`. There is nothing to
run; just open the PR that way.
- **PR source checker:** verifies the PR comes from a branch of this repository (not a fork) other than `dev` or `main`,
and targets `dev`. There is nothing to run; just open the PR that way.

- **Version check:** verifies the version in `pyproject.toml` was bumped relative to `dev`:

```bash
git remote add upstream https://github.com/pesu-dev/auth.git # skip if you already have it
git fetch upstream
git show upstream/dev:pyproject.toml > /tmp/base_pyproject.toml
git fetch origin
git show origin/dev:pyproject.toml > /tmp/base_pyproject.toml
python3 .github/scripts/check_version_bump.py --base-pyproject /tmp/base_pyproject.toml \
--head-pyproject pyproject.toml --head-lock uv.lock --base-ref dev
```
Expand Down
8 changes: 4 additions & 4 deletions docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,10 +61,10 @@ failure there after a PESU Academy release usually means their API changed rathe
The tests that are not marked `secret_required` still call PESU Academy (with invalid credentials), so
only `tests/unit/` runs offline.

In CI, pull requests come from forks, and GitHub withholds secrets from fork pull requests. So
the *Test suite & coverage* job of the *CI Checks* workflow runs the reduced suite on every pull request -- it says so in the run's summary
-- and the live tests only run once the change reaches `dev`. Run them locally before you open a
pull request; CI will not cover them for you.
In CI, pull requests come from branches of this repository, which receive the repository's secrets. So the *Test suite &
coverage* job of the *CI Checks* workflow runs the live tests on every pull request, again in the merge queue, and on
every push to `dev`. Dependabot's pull requests are the exception: GitHub gives the runs Dependabot triggers no
repository secrets. A run without the secrets runs the reduced suite and says so in the run's summary.

## Benchmarks

Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[project]
name = "pesu-auth"
version = "5.9.0"
version = "5.10.0"
description = "A simple API to authenticate PESU credentials using PESU Academy."
readme = "README.md"
requires-python = ">=3.14"
Expand Down
4 changes: 2 additions & 2 deletions scripts/run_tests.py
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,8 @@ def run_tests() -> int:
command = ["pytest", *COVERAGE_ARGS, "--disable-warnings", "-v", "-s"]
if not test_username or not test_password:
# The coverage gate applies here too. It used to be dropped along with the live tests,
# which meant a pull request could lower coverage without any check noticing -- and every
# pull request takes this path, since fork PRs never receive secrets.
# which meant a run without credentials, such as a local one without a .env or CI on a
# Dependabot pull request (which gets no secrets), could lower coverage without any check noticing.
announce_skipped_live_tests()
command += ["-m", "not secret_required"]
else:
Expand Down
2 changes: 1 addition & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading