diff --git a/.gitignore b/.gitignore index 3c0b971515..252ab1bb55 100644 --- a/.gitignore +++ b/.gitignore @@ -40,3 +40,15 @@ mprofile_*.dat # Briefcase .briefcase + +# AI tooling (SpecKit v0.8.0) +.opencode/ +.specify/scripts +.specify/templates +.specify/extensions.yml +.specify/extensions +.specify/init-options.json +.specify/integration.json +.specify/integrations +.specify/workflows +.specify/workflow.yml diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md new file mode 100644 index 0000000000..1c6588d643 --- /dev/null +++ b/.specify/memory/constitution.md @@ -0,0 +1,130 @@ + + +# Toga Constitution + +Toga is a Python native, OS native GUI toolkit published under the BSD-3-Clause license as part of the BeeWare suite. This constitution defines the non-negotiable engineering principles and governance rules that all contributions — human or AI-assisted — MUST satisfy. + +## Core Principles + +### I. Cross-Platform Backend Parity + +Every public API added to `toga-core` MUST be backed by a concrete implementation plan for the supported production backends (Cocoa, GTK, Qt, Winforms, iOS, Android, Textual, Web). A core API MUST NOT be merged unless it is either (a) implemented on every production backend, or (b) accompanied by a documented, time-boxed `NotImplementedError` surface and a tracking issue per missing backend. + +The Dummy backend MUST always implement the full core API surface so that `toga-core` tests can run without a GUI. + +Rationale: Toga's value proposition is that a single Python codebase renders natively everywhere. Backend drift silently erodes that contract; making parity a merge precondition prevents the library from accumulating platform-exclusive features disguised as cross-platform ones. + +### II. Native Look, Feel, and Behavior + +Widgets MUST delegate presentation, input handling, accessibility, and platform conventions to the host operating system's native toolkit. Custom drawing, emulated controls, or cross-platform re-skinning of native widgets are prohibited in production backends unless the host platform offers no native equivalent; any such exception MUST be justified in the PR and recorded in the backend's documentation. + +Rationale: "Native" is not a marketing term — it is the user-visible behaviour contract (keyboard shortcuts, focus rings, scroll physics, screen reader semantics, dark-mode response) that distinguishes Toga from web-view wrappers. Violating this principle breaks the product promise made on the project homepage. + +### III. Comprehensive Automated Testing (NON-NEGOTIABLE) + +All new or modified Toga code MUST ship with automated tests, and merged changes MUST maintain 100% branch coverage for `toga-core` and Travertino as reported by `tox -m test`. Backend behaviour MUST be validated by the testbed app (`briefcase dev --app testbed --test` or equivalent `briefcase run` for mobile) on every backend the change affects. + +- Core/Travertino changes: unit tests under the respective `tests/` directory, run via `tox -m test-core` / `tox -m test-trav`. +- Backend changes: probes and scenarios under `testbed/`. +- Bug fixes MUST include a regression test that fails before the fix and passes after. +- Coverage decreases MUST NOT be waived with `# pragma: no cover` except for the cases already whitelisted in the root `pyproject.toml` coverage rules. + +Rationale: Toga supports seven production backends across desktop and mobile; without mechanical, enforced coverage the combinatorial space becomes untestable and regressions reach users. 100% coverage is an existing, documented contract of the project and is preserved here as a constitutional rule. + +### IV. Public API Stability and Documented Change + +Every change visible to Toga users MUST be accompanied by: + +1. A change note file in `changes/` named `..md` where `` is one of `feature`, `bugfix`, `removal`, `doc`, or `misc`, following the existing towncrier convention. +2. User-facing documentation under `docs/en/` for any new feature, new public API, or behavioural change. Reference material MUST be updated alongside the code — documentation is not a follow-up task. +3. An explicit deprecation path for any removal or incompatible change: at minimum one release carrying a `DeprecationWarning` before the behaviour is removed, and a `removal` change note when the removal lands. Breaking changes without a deprecation period require MAJOR version justification in the PR description. + +Rationale: Toga is a public library with downstream applications; silent behavioural drift is indistinguishable from breakage for those users. Change notes and docs are the audit trail that makes semantic versioning honest. + +### V. Contributor Accountability + +Contributors are responsible for the changes they submit, regardless of how those changes were produced. Specifically: + +- PRs MUST follow the documented submission process (branch from `main`, pre-commit checks pass, change note included, CI green). +- Use of autonomous coding tools is permitted but the submitter bears full responsibility for correctness, licensing compatibility, and adherence to this constitution; the BeeWare AI Policy applies in full. +- Reviewers MUST verify the change against the principles above before approving; a PR that fails any principle MUST be rejected or revised, not merged with a waiver. +- All participation is governed by the BeeWare Code of Conduct. + +Rationale: Automation and scale make it tempting to treat review as rubber-stamping. Binding the human on both sides of the PR to the same principles keeps quality independent of who (or what) typed the diff. + +## Additional Constraints + +**Supported runtime platforms**: Toga MUST continue to support the Python versions listed in `core/pyproject.toml` classifiers and the backends enumerated under the repository root (`cocoa/`, `gtk/`, `qt/`, `iOS/`, `android/`, `winforms/`, `textual/`, `web/`). Dropping a supported Python version or backend requires a MINOR-or-greater release and an explicit deprecation notice in `changes/`. + +**Toolchain**: The canonical developer toolchain is `tox` for tests, `ruff` for lint and import sorting (configured in root `pyproject.toml`), `pre-commit` for local enforcement, `briefcase` for packaging and testbed execution, and `towncrier` for release-note assembly. Alternative tools are permitted locally but MUST NOT replace these in CI or documented contributor workflows without a constitutional amendment. + +**Licensing**: All first-party code MUST remain BSD-3-Clause compatible. Dependencies with incompatible licenses MUST NOT be added to runtime requirements of `toga-core`, Travertino, or any production backend. + +**Style**: Code MUST satisfy the Toga code style guide and the automated checks configured in `pre-commit`. Style disagreements are resolved by the style guide, not by individual PR debate. + +## Development Workflow + +1. **Issue or proposal first**: Non-trivial features start with a GitHub issue or discussion so design can be reviewed before implementation effort is spent. Bug fixes MAY skip this if a reproducer is evident. +2. **Feature branch**: Work is performed on a branch off `main`; direct pushes to `main` are prohibited except by release automation. +3. **Local verification**: Before opening a PR, contributors MUST run `tox -m test` (core + Travertino, 100% coverage) and the testbed for any backend their change affects. Pre-commit hooks MUST pass. +4. **Pull request**: PRs MUST include a change note, updated docs where applicable, and a description that references the issue being closed and the backends exercised. +5. **Review**: At least one maintainer review is required. Reviewers MUST explicitly confirm the five Core Principles are upheld. CI MUST be green before merge. +6. **Merge**: Squash-merge is the default; the squash commit message MUST summarise the user-visible change, not the intermediate work. +7. **Release**: Releases are cut from `main` by project maintainers using `towncrier` to assemble release notes from `changes/`. Version numbers follow the scheme declared in `core/pyproject.toml` and the project release policy; Toga's own release versioning is independent of this constitution's version. + +## Governance + +This constitution supersedes ad-hoc practice. When a contributing document, code comment, or review conflicts with the constitution, the constitution prevails and the conflicting document MUST be updated. + +**Amendment procedure**: Proposed amendments are opened as a PR that edits this file, with a description explaining the motivation, the principle(s) affected, and the version bump being requested. Amendments MUST be reviewed and approved by at least two project maintainers and MUST update the Sync Impact Report at the top of this file. + +**Versioning policy**: This constitution uses semantic versioning independent of Toga's release version. + +- **MAJOR**: A principle is removed, a principle's meaning is narrowed or reversed, or a governance rule is dropped. +- **MINOR**: A new principle, section, or materially expanded rule is added. +- **PATCH**: Clarifications, wording, typo fixes, or non-semantic refinements. + +**Compliance review**: Every PR review MUST include an explicit check against the Core Principles. Maintainers SHOULD perform a constitutional audit at each minor release of Toga, checking that templates, workflows, and CI continue to enforce these principles; any drift MUST be filed as an issue and resolved before the next release. + +**Agent guidance**: Autonomous agents (via `AGENTS.md` or equivalent) operating on this repository MUST load and apply this constitution for any task that changes public API, adds or removes backends, modifies test coverage, or touches release tooling. + +**Version**: 1.0.0 | **Ratified**: 2026-04-24 | **Last Amended**: 2026-04-24 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..b1d03f2a82 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,180 @@ +# Toga - Agent Development Guide + + +For additional context about technologies to be used, project structure, shell commands, and other important information, read the current plan + + +This file tells autonomous coding agents (and human contributors using agent tools) how to be productive in this repository without breaking it. It is operational guidance; the binding rules live in `.specify/memory/constitution.md` and the contribution docs under `docs/en/how-to/contribute/`. When this file disagrees with either, the constitution wins. + +## What Toga is + +Toga is a Python-native, OS-native GUI toolkit published under BSD-3-Clause as part of the BeeWare suite. A single `toga-core` API is rendered by a platform-specific backend so that one Python codebase produces native apps on macOS, Windows, Linux, iOS, Android, Web, and terminal. + +## Repository layout + +| Path | What it contains | +| --- | --- | +| `core/` | `toga-core` — the public API and shared widget contracts. | +| `travertino/` | Style and layout engine used by `core`. | +| `dummy/` | Reference headless backend; MUST implement the full core API so core tests can run without a GUI. | +| `cocoa/` | macOS backend. | +| `gtk/` | Linux/GTK backend (GTK3 stable, GTK4 experimental). | +| `winforms/` | Windows backend. | +| `iOS/` | iOS backend. | +| `android/` | Android backend. | +| `textual/` | Terminal backend. | +| `web/` | Web backend. | +| `qt/` | Linux/Qt backend. | +| `positron/` | Briefcase plugin for generating apps where the UI has been defined with web tools. Similar to Electron, but using Python for the web server | +| `testbed/` | Briefcase app used to validate backend behaviour on a real platform. | +| `docs/en/` | User and contributor documentation (MkDocs, `mkdocs.en.yml`). | +| `changes/` | Towncrier fragments (`..md`) — one per user-visible change. | +| `examples/`, `demo/` | Standalone sample apps. | +| `.specify/` | SpecKit workflow assets (constitution, templates, extensions). | + +Do not create new top-level directories without a clear constitutional reason; extend existing ones. + +## Non-negotiables (from the constitution) + +1. **Backend parity.** A new `toga-core` API MUST have a concrete implementation plan for every production backend. The Dummy backend MUST always implement the full surface. +2. **Native behaviour.** Production backends MUST delegate to the native toolkit. No emulated/custom-drawn widgets without documented justification. +3. **Comprehensive tests (NON-NEGOTIABLE).** 100% line coverage for `core` and `travertino`. Backend changes MUST be exercised via `testbed/`. Bug fixes MUST include a regression test that fails before the fix. +4. **Documented change.** Every user-visible change MUST include a `changes/..md` fragment and updated docs. Breaking changes require a deprecation release. +5. **Contributor accountability.** The submitter owns the diff, regardless of AI assistance. Follow the BeeWare Code of Conduct and AI Policy. + +Any PR failing one of these is rejected, not waived. + +## Toolchain + +- **Python**: 3.10–3.14 (see `core/pyproject.toml` classifiers). +- **Task runner**: `tox` (with `tox-uv`). Install the dev tooling via `uv pip install --group dev` at the repo root, or let `tox` bootstrap. +- **Lint/format**: `ruff` (check + format), `codespell`, `rumdl` (Markdown), configured in root `pyproject.toml`. +- **Pre-commit**: `pre-commit run --all-files` — MUST pass before PR. +- **Packaging / testbed driver**: `briefcase`. +- **Release notes**: `towncrier` (config in root `pyproject.toml`). +- **Docs**: MkDocs; built with the `docs` dependency group. + +Do not replace or bypass these tools. Add new dependencies only with a clear need and a compatible license (BSD-3-Clause friendly). + +## Canonical commands + +Run from the repository root unless noted. + +```console +# Everything pre-commit checks (ruff, format, codespell, rumdl, etc.) +pre-commit run --all-files + +# Core + Travertino test suites with coverage (MUST be 100%) +tox -m test + +# Just core +tox -m test-core + +# Just Travertino +tox -m test-trav + +# A single test file against core +tox -e py-cov -- core/tests/path/to/test_file.py + +# A single test file against Travertino +tox -e py-trav -- travertino/tests/path/to/test_file.py + +# Towncrier draft (preview assembled release notes) +tox -e towncrier-check + +# Docs lint +tox -e docs-lint +``` + +### Testbed (backend validation) + +The core suite uses the Dummy backend. Real backend behaviour is validated through the testbed app. Install only the backend under test in your virtualenv, then: + +```console +# Desktop (from testbed/) +briefcase dev --app testbed --test + +# GTK variants (Linux) +briefcase dev --app testbed --test +TOGA_GTK=4 TOGA_GTKLIB=None briefcase dev --app testbed --test +TOGA_GTK=4 TOGA_GTKLIB=Adw briefcase dev --app testbed --test + +# Qt (Linux) +briefcase dev --app testbed-qt --test + +# Textual (Linux) +briefcase dev --app testbed-textual --test + +# Mobile (requires the relevant SDK/toolchain) +briefcase run android --app testbed --test +briefcase run iOS --app testbed --test # macOS host only + +# Subset with slow mode for visual inspection +briefcase dev --app testbed --test -- tests/widgets/test_button.py --slow +``` + +**Do not touch the keyboard/mouse while the testbed is running** — it drives input programmatically and will desync. + +## Change notes + +Every user-visible PR needs a file in `changes/`: + +```text +changes/..md +``` + +`` MUST be one of: `feature`, `bugfix`, `removal`, `doc`, `misc`. Content is one or more sentences of past-tense prose describing the user-visible change. `misc` entries are hidden from release notes and appropriate for purely internal changes. Do not edit `docs/en/about/releases.md` directly; towncrier assembles it at release time. + +## Coding conventions + +- Follow the Toga code style guide linked from `CONTRIBUTING.md`. Ruff enforces most of it; do not disable rules locally. +- Keep public API surface minimal and documented. New public names MUST appear in reference docs under `docs/en/reference/api/`. +- Type hints: use them on public API; keep them consistent with the `.pyi` stub (`core/src/toga/__init__.pyi`) when applicable. That stub is excluded from Ruff — hand-edit it carefully. +- `# pragma: no cover` is reserved for the cases already whitelisted in `tool.coverage.coverage_conditional_plugin.rules`. Do not introduce new ones to work around missing tests. +- `filterwarnings = ["error"]` is set for pytest; warnings in tests are failures. Either fix the root cause or add a scoped, commented `pytest.warns(...)` / `filterwarnings` mark. +- `isort` config in root `pyproject.toml` lists the first-party backend packages; add new packages there if you create one. + +## Documentation expectations + +- Every new public API, widget, or behavioural change MUST update `docs/en/` in the same PR. +- Tutorials live under `docs/en/tutorial/`, how-tos under `docs/en/how-to/`, reference under `docs/en/reference/`, topic explanations under `docs/en/topics/`. +- Build-time doc linting runs through `tox -e docs-lint`; fix anything it reports. +- Markdown files in this project (including `AGENTS.md`, `docs/en/`, and `changes/` fragments) must **not** use hard line breaks to enforce an 80-character column limit. Each paragraph or list item must be written as a single unbroken line, regardless of its length. Let the reader's editor or renderer handle wrapping. This rule applies to all prose. Code blocks, directory trees, and other pre-formatted blocks are exempt — keep those readable within their own constraints. When writing or editing any `.md` file, do not insert newlines mid-sentence or mid-paragraph to stay within 80 columns. +- Follow the BeeWare documentation style guide (linked from `CONTRIBUTING.md`). + +## Pull-request workflow + +1. Branch off `main` with a descriptive name. Do not push to `main`. +2. Make the smallest change that addresses one issue. Avoid scope creep; file a separate issue/PR for drive-by refactors. +3. Before opening the PR, run locally: + - `pre-commit run --all-files` + - `tox -m test` (expect 100% coverage) + - Testbed on any backend the change affects +4. Include in the PR: + - A `changes/..md` fragment + - Docs updates when user-visible + - A description naming the issue closed and the backends exercised +5. CI MUST be green. Reviewers confirm the five constitutional principles; failures are fixed, not waived. +6. Default merge strategy is squash; the squash message is what users will read, so make it describe the user-visible change. + +## Agent-specific rules + +Agents operating in this repo MUST: + +- Load `.specify/memory/constitution.md` before any change that affects public API, backends, test coverage, or release tooling. +- Prefer editing existing files over creating new ones. Never proactively create new top-level files or directories. +- Keep the ` ... ` block at the top of this file intact; SpecKit commands inject plan context there. +- Never add `# pragma: no cover`, `# noqa`, or disable Ruff/codespell rules inline to pass CI; diagnose and fix the underlying issue. +- Never commit secrets, API keys, `.env` files, or contributor PII. +- Never rewrite Git history on `main` or force-push shared branches. +- When uncertain about backend parity or API shape, open an issue or discussion before implementing; Toga favours design-first for anything non-trivial (see `docs/en/how-to/contribute/how/propose-feature.md`). +- Disclose AI assistance in the PR description where it is material to review, per the BeeWare AI Policy. + +## Where to look next + +- `CONTRIBUTING.md` — entry point for all contributors. +- `.specify/memory/constitution.md` — binding project principles. +- `docs/en/how-to/contribute/` — style guides, PR process, review guide, scope-creep guide, AI policy. +- `docs/en/reference/platforms/` — per-backend requirements and status. +- Toga documentation site: +- BeeWare community and Code of Conduct: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9df409a8e6..66490796ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,37 @@ -# Contributing +# All Contributions Welcome -BeeWare <3's contributions! +It's not just about code. A successful software project requires documentation, design skills, feedback and bug reports. The BeeWare project recognizes that all contributions are important - not just the ones that come as a pull request on GitHub. -Please be aware that BeeWare operates under a [Code of Conduct](https://beeware.org/community/behavior/code-of-conduct/). +## How to contribute -If you'd like to contribute to Toga development, our [contribution guide](https://toga.beeware.org/en/latest/how-to/contribute/) details how to set up a development environment, and other requirements we have as part of our contribution process. +If you'd like to contribute to Toga, our [contribution guide](https://toga.beeware.org/en/latest/how-to/contribute/) has details on how to pick a way to contribute, how to set up a development environment, and other requirements we have as part of our contribution process. + +### Code of Conduct + +BeeWare operates under a [Code of Conduct](https://beeware.org/community/behavior/code-of-conduct/). All participation the BeeWare community is governed by this code. + +### AI contributions + +We neither encourage nor prohibit the use of autonomous coding tools when contributing to BeeWare projects. However, if you have used an autonomous coding tool to support your work processes, all contributions are you make are ultimately **your** responsibility. + +Our [AI Policy](https://toga.beeware.org/en/latest/how-to/contribute/policies/ai-policy/) has the full details of your obligations if you choose to use an AI tool when contributing to BeeWare. + +### Issues + +We have a [process and requirements for creating new issues](https://toga.beeware.org/en/latest/how-to/contribute/how/new-issue/). + +### Code style guide + +We have a [code style guide](https://toga.beeware.org/en/latest/how-to/contribute/style/code-style-guide/) all code must follow. This is partially enforced by automated pre-commit checks; our guide on [setting up a development environment](https://toga.beeware.org/en/latest/how-to/contribute/style/docs-style-guide/) describes how to configure these automated checks. + +### Testing + +We require that all new code is exercised by automated tests. Our contribution guide describes [how to run the project test suite](https://toga.beeware.org/en/latest/how-to/contribute/how/write-code/). + +### Documentation + +We require that all new features have full user documentation. We have a [documentation style guide](https://beeware.org/contributing/guide/style/docs-style-guide/) that all documentation should follow. Our contribution guide has details on [how to build and preview project documentation](https://beeware.org/contributing/guide/how/build-docs/). + +### Pull Requests + +We have a [process for submitting a PR](https://toga.beeware.org/en/latest/how-to/contribute/how/submit-pr/) that all contributions must follow. diff --git a/README.md b/README.md index d539fdc682..7b844ae5d3 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,6 @@ We foster a welcoming and respectful community as described in our [BeeWare Comm ## Contributing -If you experience problems with Toga, [log them on GitHub](https://github.com/beeware/toga/issues). +If you experience problems with Toga, [log them on GitHub](https://toga.beeware.org/en/latest/how-to/contribute/how/new-issue/). If you'd like to contribute to Toga development, our [contribution guide](https://toga.beeware.org/en/latest/how-to/contribute/) details how to set up a development environment, and other requirements we have as part of our contribution process. diff --git a/changes/4344.feature.md b/changes/4344.feature.md new file mode 100644 index 0000000000..6eb54bdd60 --- /dev/null +++ b/changes/4344.feature.md @@ -0,0 +1 @@ +The Toga repository now has an `AGENTS.md` file and [Spec Kit](https://github.github.com/spec-kit/) constitution to provide assistance for Generative AI tools. diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index 4a66c3f7ed..bd71c8ff89 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -31,6 +31,8 @@ - What happens next? - [Pull request review process](how-to/contribute/next/pr-review.md) - [Release process](how-to/contribute/next/release.md) + - Policies + - [AI Policy](how-to/contribute/policies/ai-policy.md) - Style guides - [Code style guide](how-to/contribute/style/code-style-guide.md) - [Documentation style guide](how-to/contribute/style/docs-style-guide.md) diff --git a/docs/en/how-to/contribute/policies/ai-policy.md b/docs/en/how-to/contribute/policies/ai-policy.md new file mode 100644 index 0000000000..e17e99981e --- /dev/null +++ b/docs/en/how-to/contribute/policies/ai-policy.md @@ -0,0 +1,3 @@ + + +{% extends "contribute/policies/ai-policy.md" %} diff --git a/pyproject.toml b/pyproject.toml index 607bb23738..a993811491 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -172,6 +172,7 @@ dev = [ # and the docs contribution guide. docs = [ "beeware-docs-tools @ git+https://github.com/beeware/beeware-docs-tools", + # "beeware-docs-tools @ file://../beeware-docs-tools", "tabulate==0.9.0", "mkdocs-redirects==1.2.2", "mkdocs-exclude==1.0.2", diff --git a/tox.ini b/tox.ini index 01810c46ed..cc56922afc 100644 --- a/tox.ini +++ b/tox.ini @@ -98,6 +98,8 @@ docs_dir = {tox_root}{/}docs{/}en [testenv:docs{,-lint,-all,-live,-en}] # Docs are always built on Python 3.12. See also the RTD config and contribution docs. base_python = py312 +setenv = + DISABLE_MKDOCS_2_WARNING = true skip_install = True dependency_groups = docs deps =