Skip to content

Contributing and releases

Issues and pull requests

  • Use GitHub Issues for bugs and feature ideas.
  • Fork the repository, push a branch on your fork, and open a pull request into main.
  • Public forks: the first time a new contributor opens a PR, a maintainer may need to approve workflow runs on GitHub (default security behavior).

Non-members cannot push directly to this repo; they read, fork, and propose changes via PR.

Local development

uv sync --all-groups
pytest

Build the docs locally:

uv run mkdocs serve

Documentation site (GitHub Pages)

The Docs workflow builds with MkDocs and deploys on every push to main.

One-time repository setup (maintainers):

  1. Settings → Pages
  2. Set Source to GitHub Actions (not “Deploy from a branch”).
  3. After the next successful run on main, the site is available at the URL shown under Pages (default: https://grosgradient.github.io/colandix/).

If you add a custom domain later:

  1. Add a CNAME at the repo root (one line: your hostname, e.g. docs.example.com).
  2. In DNS, point that hostname to grosgradient.github.io with a CNAME record.
  3. Enter the same hostname under Settings → Pages → Custom domain and wait for the TLS certificate.
  4. Set site_url in mkdocs.yml (and optional project.urls in pyproject.toml) to the live docs URL.

PyPI releases (Trusted Publisher)

Publishing uses release.yml: it runs only when a GitHub Release is published, builds the package with uv build, and uploads with pypa/gh-action-pypi-publish via OIDC — no PyPI token in GitHub secrets.

One-time PyPI setup (project owner):

  1. Create or claim the colandix project on PyPI.
  2. Publishing → Add a trusted publisher (preferred) or equivalent:
  3. Owner: GitHub organization (e.g. GrosGradient)
  4. Repository: colandix
  5. Workflow name: release.yml
  6. Environment: leave default unless you use a named GitHub Environment

Maintainer release checklist

  1. Update CHANGELOG.md and bump version in pyproject.toml following SemVer.
  2. Merge to main.
  3. Create a GitHub Release with a tag vX.Y.Z matching the version (e.g. v0.1.0).
  4. Confirm the Release workflow succeeds and the new version appears on PyPI.
  5. Confirm docs deployed as expected (Pages workflow on main).

Org-level notes (outside this repo)

  • Organization profile README: must live at [org]/.github repository under profile/README.md (not .github/README.md at the root of that repo).
  • Repo access: add teams or people under Settings → Collaborators with Write or Maintain as needed; consider branch protection on main.