DOC: document multi-phase work and release procedure; add AGENTS.md

AGENTS.md

@@ -0,0 +1,34 @@
+# Agent instructions for QuantEcon.py
+
+Guidance for AI coding agents working in this repository. Human contributors should start from
+[CONTRIBUTING.md](CONTRIBUTING.md) and the rendered guide it links to; everything there applies to
+agents too — this file only adds the essentials and repo-specific conventions.
+
+## Quickstart
+
+- Environment: `conda env create -f environment.yml` (creates `qe`), activate it, then
+  `flit install --symlink`. Environment creation takes several minutes — let it finish.
+- Tests: `pytest quantecon` (bare `pytest` also works — `pytest.ini` scopes collection to
+  `quantecon/`). The full suite takes minutes; run `pytest quantecon/<module>/tests/...` while
+  iterating. Much of the library is Numba-jitted, so the first call of anything compiled is slow —
+  don't mistake JIT compilation for a hang. Slow tests can be skipped with `-m "not slow"`.
+- Lint (same selects as CI): `flake8 --select=F401,F405,E231 quantecon`
+- The `ci/` directory holds CI-only assets (for example the WASM smoke suite in `ci/wasm/`). They
+  are not part of the shipped package and are run by explicit path in workflows — keep imports of
+  CI-only dependencies (such as `playwright`) out of anything bare `pytest` collects.
+
+## Working procedure
+
+- Make small, self-contained pull requests against `main`; each must be green in CI and safe to
+  release on its own. Do not create long-lived feature branches — multi-phase work merges to `main`
+  incrementally. See "Multi-phase projects and releases" in
+  [docs/source/contributing.rst](docs/source/contributing.rst) for the full procedure and its
+  rationale.
+- Keep `main` releasable: publishing to PyPI is automated on `v*` tags, so anything merged can ship
+  at any time. Do not change default behaviour of library functions unless that is the reviewed
+  purpose of the change.
+- Larger campaigns are tracked as an umbrella issue plus sub-issues under a milestone; read the
+  umbrella issue before working on a sub-issue, and record findings in the issues — they are the
+  durable record.
+- Release notes live on [GitHub releases](https://github.com/QuantEcon/QuantEcon.py/releases);
+  `CHANGELOG.md` only points there. Do not add per-PR changelog entries.

docs/source/contributing.rst

@@ -80,6 +80,34 @@ The rendered pages are written to ``docs/build/html``. Once you open a pull requ
 documentation is also built automatically by `Read the Docs <https://readthedocs.org>`_ and linked from
 the pull request checks.
 
+Multi-phase projects and releases
+---------------------------------
+
+Some improvements are too large for a single pull request — for example a compatibility campaign that
+touches CI, library code and packaging. We organise this kind of work as follows (the JupyterLite/WASM
+browser-support campaign, `#925 <https://github.com/QuantEcon/QuantEcon.py/issues/925>`_, is the
+reference example):
+
+- **Track the work on GitHub.** Open an umbrella issue holding the plan, with one sub-issue per
+  deliverable, all grouped under a milestone. Write enough context into the issue bodies that the
+  issues themselves are the durable record.
+
+- **Merge to** ``main`` **as you go — do not use long-lived feature branches.** Each pull request
+  should be small, individually reviewed, green in CI and safe to release on its own. Integration
+  branches rot as ``main`` moves, their pull requests bypass the required CI contexts configured for
+  ``main``, and workflows only become ``workflow_dispatch``-able once they exist on the default
+  branch.
+
+- **Keep** ``main`` **releasable after every merge.** Publishing to PyPI is automated on ``v*`` tags,
+  so anything merged can ship at any time. Library changes must leave default behaviour unchanged
+  unless that change is the reviewed purpose of the pull request. CI and test scaffolding (workflows,
+  the ``ci/`` directory) is not part of the shipped package, so it can land freely.
+
+- **Cut an intermediate release when a later phase depends on shipped fixes.** Downstream consumers
+  (conda-forge, emscripten-forge, the lecture repositories) only see released versions, so don't hold
+  the release until a campaign is finished — release as soon as the milestone's library fixes have
+  landed, and treat the milestone as the release checklist.
+
 Further questions
 -----------------