From 8475504afaf8f384f6b42234716cd78dcbc18e1f Mon Sep 17 00:00:00 2001 From: sunmodza Date: Mon, 28 Sep 2026 19:39:40 +0700 Subject: [PATCH 1/2] Make contributions easier and add a stable CI gate --- .github/ISSUE_TEMPLATE/bug_report.md | 14 +++++ .github/ISSUE_TEMPLATE/feature_request.md | 10 +++ .github/PULL_REQUEST_TEMPLATE.md | 11 ++++ .github/workflows/tests.yml | 31 +++++++++ CONTRIBUTING.md | 76 +++++++++++------------ README.md | 4 +- README.pypi.md | 4 +- 7 files changed, 107 insertions(+), 43 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..c917a38 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,14 @@ +--- +name: Bug report +about: Report incorrect behavior or a crash +--- + +## Command and CPython version + +## Minimal source that reproduces the bug + +## Expected behavior + +## Actual behavior + +Remove credentials and private data before sharing source or logs. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..0ee1ef6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,10 @@ +--- +name: Feature request +about: Suggest a change to Aiython +--- + +## Problem or use case + +## Proposed behavior + +## Small example diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..011d507 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,11 @@ +## What changed + + + +## How you tested it + + + +## Documentation + + diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 9fe2fd7..14c7304 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -81,3 +81,34 @@ jobs: uuid-dev zlib1g-dev libnsl-dev libtirpc-dev - name: Build and test patched CPython run: uv run --locked --python ${{ matrix.python-version }} python scripts/build_cpython_hooks.py ${{ matrix.python-version }} + + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0 + with: + python-version: "3.11.16" + version: latest-known + enable-cache: false + - run: uv run --locked --python 3.11.16 zensical build --clean --strict + - run: uv run --locked --python 3.11.16 python scripts/check_docs_site.py + + required: + name: CI + if: ${{ always() }} + needs: [package, test, native-hooks, docs] + runs-on: ubuntu-latest + steps: + - name: Require every job to pass + env: + PACKAGE: ${{ needs.package.result }} + TEST: ${{ needs.test.result }} + NATIVE_HOOKS: ${{ needs.native-hooks.result }} + DOCS: ${{ needs.docs.result }} + run: | + for result in "$PACKAGE" "$TEST" "$NATIVE_HOOKS" "$DOCS"; do + test "$result" = success || exit 1 + done diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e9b22e4..2f23705 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,51 +1,45 @@ # Contributing to Aiython -Thanks for helping improve Aiython. Bug reports, documentation fixes, examples, -and focused code changes are welcome. +Bug reports, documentation fixes, examples, and focused code changes are welcome. -## Before you change code +## Start with an issue -- Search existing issues and pull requests for related work. For a larger change, - open an issue first so the behavior and scope can be discussed. -- Keep Python in charge of execution order and side effects. New behavior should - apply generally, rather than depend on a particular prompt or example. -- Keep code, examples, documentation, and user-facing messages in English. +Search existing issues and pull requests first. For a larger change, open an +issue to discuss the behavior before writing code. A bug report should include +the Aiython command, CPython version, expected and actual behavior, and a small +reproducible script. Remove credentials and private data from logs and examples. -## Develop locally +## Make a change -Install CPython 3.11+ and [uv](https://docs.astral.sh/uv/), then run: +Fork the repository and create a branch from `main`, such as `fix/error-message` +or `docs/getting-started`. Install CPython 3.11+ and [uv](https://docs.astral.sh/uv/): ```bash -uv sync -uv run aiython --explain examples/recipes/03_loop.py -uv run python -m unittest discover -s tests -q +uv sync --locked +uv run --locked aiython --explain examples/recipes/03_loop.py +uv run --locked python -m unittest discover -s tests -q ``` -The default test suite mocks provider calls and requires no API key. Use -`--explain` to inspect an example without executing it. If a change affects a -provider or capability, add an offline contract test for its request, response, -and error behavior; live API checks are optional and may incur charges. - -The documentation website uses the Markdown files in `docs/`. Preview it with -`uv run zensical serve` and check the production build with -`uv run zensical build --clean --strict`, then run -`uv run python scripts/check_docs_site.py` to check rendered examples and links. -The public site is built from a release tag after the PyPI publish job succeeds. -It is served from the separate public -`aiython-docs` repository; this source repository remains private. Link to pages -inside `docs/` rather than private repository files. - -## Submit a change - -Keep a pull request focused and describe the user-visible behavior, why it -changed, and how you verified it. Update the README or relevant guide when an -interface changes. Include a small reproducible program for runtime bugs and -check that Python statements and side effects still run in their normal order. - -For a bug report, include the Aiython command, expected and actual behavior, -Python version, and a minimal source file. `--stats` output can help locate -latency or provider errors. Remove API keys, credentials, and private input -before sharing logs or source. - -By contributing, you agree that your contribution is licensed under the -[MIT license](LICENSE). +The local tests mock provider calls and need no API key. Use `--explain` to +inspect AI boundaries without running the program. When changing a capability +or provider, add an offline test for its request, response, and error behavior. + +For documentation changes, run: + +```bash +uv run --locked zensical build --clean --strict +uv run --locked python scripts/check_docs_site.py +``` + +## Open a pull request + +Push your branch and open a pull request against `main`. Explain what changed, +why, and how you tested it. Update a relevant guide or example when behavior +changes. Keep Python in charge of execution order and side effects, and keep +code and documentation in English. + +`main` accepts changes through pull requests. CI checks the package, docs, +Python 3.11–3.14, and patched CPython hooks before a merge. The release workflow +publishes PyPI and the documentation site from version tags. + +Contributions are licensed under the [MIT license](LICENSE). diff --git a/README.md b/README.md index 010f1b8..337095a 100644 --- a/README.md +++ b/README.md @@ -47,4 +47,6 @@ aiython app.py The same works for modules: `python -m package` → `aiython -m package`. Your script and its arguments stay the same. Aiython checks declared types and can call AI for inline requests or eligible errors. -Aiython is not a sandbox: AI tools run with your process permissions, and relevant code or data may be sent to your provider. [MIT licensed](LICENSE). +Aiython is not a sandbox: AI tools run with your process permissions, and relevant code or data may be sent to your provider. + +[Contributing](CONTRIBUTING.md) · [MIT license](LICENSE) diff --git a/README.pypi.md b/README.pypi.md index e188898..45af9cc 100644 --- a/README.pypi.md +++ b/README.pypi.md @@ -45,4 +45,6 @@ Preview AI calls without running the script: `aiython --explain tickets.py`. [Documentation](https://sunmodza.github.io/aiython-docs/) · [Examples](https://sunmodza.github.io/aiython-docs/examples/) · [Installation](https://sunmodza.github.io/aiython-docs/getting-started/) -Aiython is not a sandbox: AI tools run with your process permissions, and relevant code or data may be sent to your provider. MIT licensed. +Aiython is not a sandbox: AI tools run with your process permissions, and relevant code or data may be sent to your provider. + +[Contributing](https://github.com/sunmodza/aiython/blob/main/CONTRIBUTING.md) · MIT licensed. From 3fd36887fc443b8b5d04e4e18c53d1125641a82e Mon Sep 17 00:00:00 2001 From: sunmodza Date: Mon, 28 Sep 2026 19:40:45 +0700 Subject: [PATCH 2/2] Run offline CI once per pull request --- .github/workflows/tests.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 14c7304..915b695 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -2,6 +2,7 @@ name: Offline tests on: push: + branches: [main] pull_request: permissions: