diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 83cb694..2157ea6 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -10,7 +10,8 @@ body: - type: markdown attributes: value: | - Search existing issues first. Do not disclose suspected vulnerabilities here. + Search existing issues first. Report one problem per issue and use separate issues for + unrelated problems. Do not disclose suspected vulnerabilities here. - type: dropdown id: library attributes: diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml index ca17225..992dec4 100644 --- a/.github/ISSUE_TEMPLATE/feature.yml +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -7,6 +7,11 @@ labels: - "status: needs-triage" - "compatibility: affected" body: + - type: markdown + attributes: + value: | + Search existing issues first. Describe one coherent change per issue; separate unrelated + requests. Discuss the intended behavior here before opening a pull request. - type: dropdown id: library attributes: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 0d92431..056d5ba 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,9 +2,12 @@ Closes # +The issue and this PR each describe one problem or coherent change. Separate unrelated fixes. +Automated dependency updates and administrative metadata changes are exempt from the issue requirement. + ## Outcome -Describe the user-visible or standards outcome. +Describe the problem, expected behavior, and what this change does. ## Compatibility @@ -13,7 +16,14 @@ Describe the user-visible or standards outcome. ## Verification -- [ ] Tests reproduce the prior failure or verify the requested behavior +For a bug fix, record the regression command and its result on both revisions: + +- Base revision, command, and failure: +- PR revision, same command, and passing result: + +For other changes, state the relevant commands and results. + +- [ ] Verification exercises the affected public API or user workflow - [ ] Ruff lint and format checks pass - [ ] `ty` passes - [ ] Test suite passes @@ -21,6 +31,12 @@ Describe the user-visible or standards outcome. - [ ] Strict MkDocs build passes when documentation is affected - [ ] Ecosystem qualification passes +## AI assistance + +State whether you used AI tools and which parts they helped produce, including code and prose. + +- [ ] I reviewed and tested this submission and can explain its code and evidence + ## Documentation and release State the documentation, release notes, and patch-release work required after merge. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eca7af6..7a3c352 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,52 @@ # Contributing -Use the GitHub repository that owns the affected code. Cross-library policies, qualification, -documentation process, and coordination belong here; implementation defects belong in the affected -library. +These requirements apply to the current ML4T libraries and the maintained Zipline, Pyfolio, +Alphalens, and Empyrical Reloaded repositories. Use the repository that owns the affected code. +Shared policy and qualification belong in `ml4t/ecosystem`; library changes belong in that library. -Before opening an issue, search existing ecosystem and library issues. Public bug reports must state -the affected package version, environment, expected behavior, observed behavior, and a minimal -reproduction. Report suspected vulnerabilities through the private process in `SECURITY.md`. +## Start with one issue -User-visible changes and defect fixes require an issue and a pull request that closes it. Run the -quality gates in `AGENTS.md` before requesting review. +Search existing issues before opening a new one. Each issue describes one problem or coherent +change. Open separate issues for unrelated problems. + +For a bug, include the affected package version, environment, expected behavior, observed behavior, +and the smallest complete reproduction. Report suspected vulnerabilities through the private +process in [SECURITY.md](SECURITY.md). + +Discuss substantial changes in the owning issue before implementing them. Reloaded libraries accept +bug, security, and compatibility fixes; direct new feature requests to the current ML4T libraries. + +## Submit one focused pull request + +Each pull request addresses one issue and includes a closing reference, such as `Closes #123`. +Related code, tests, and documentation can belong in the same PR. Keep unrelated fixes, refactors, +and formatting changes separate. Automated dependency updates and administrative metadata changes +do not require a separate issue. + +For a bug fix, include a regression that exercises the affected public API or user workflow. Run it +against the relevant base revision and the proposed fix, and record both revisions, commands, and +results. It must fail because of the defect on the base and pass with the fix. Tests of copied logic +or source text do not establish that the behavior is corrected. + +Run the owning repository's documented quality checks before requesting review and report the +commands and results. Documentation changes need documentation checks; they do not need an +artificial regression test. This repository's commands are in [AGENTS.md](AGENTS.md). + +Verified defects must be corrected, including defects that affect numerical results. If a proposed +change alters an intended definition, annualization, sign convention, or default, agree on the +expected behavior in the owning issue and document its compatibility impact. Existing output alone +is not evidence that the implementation is correct. + +## AI assistance and accountability + +You may use AI tools for code and prose. State whether you used them and which parts they helped +produce. Review and test the submission yourself, and be able to explain the code, evidence, and +responses you submit. An automated reply does not replace understanding a review question. + +Keep concurrent submissions manageable. Wait for feedback on your first focused contribution +before opening a large series of similar PRs. + +Maintainers may ask you to split or complete a submission, or close it without detailed review when +it does not meet these requirements. You are welcome to resubmit once it does. Existing bundled PRs +may contain useful fixes; maintainers can request focused replacements so each fix can be assessed +independently. diff --git a/docs/standards/issues-and-pull-requests.md b/docs/standards/issues-and-pull-requests.md index e17500b..ececf3e 100644 --- a/docs/standards/issues-and-pull-requests.md +++ b/docs/standards/issues-and-pull-requests.md @@ -10,6 +10,11 @@ issues. It does not duplicate an owning library's implementation issue. ## Intake +The [contribution policy](https://github.com/ml4t/ecosystem/blob/main/CONTRIBUTING.md) applies to +the current ML4T and maintained Reloaded libraries. Each issue describes one problem or coherent +change; unrelated problems require separate issues. Each PR addresses its owning issue. A bundle +of unrelated fixes is not made focused by collecting them in one issue. + All libraries provide compatible forms for bugs, features, and documentation problems. Intake records the affected version, environment, observed and expected behavior, reproduction evidence where applicable, compatibility impact, and acceptance criteria. @@ -30,7 +35,18 @@ Library-specific labels may extend the vocabulary but may not redefine shared la Every non-automated user-visible change and defect fix has an associated issue. Its pull request uses a closing reference. Automated dependency updates and administrative metadata changes are exempt. External pull requests may use their own complete description as the issue record when the repository -accepts and links it explicitly. - -Automation may report, classify, and update work records with approved credentials. It never writes -to library branches. Code and documentation changes use the owning repository's pull-request process. +explicitly accepts it during triage of an existing submission. This is an intake exception, not the +default process for new submissions, and does not waive focused scope or verification. + +Bug fixes include executed evidence that the same regression fails on the relevant base and passes +with the correction through a real public API or user workflow. Contributors disclose AI assistance +and remain accountable for code and prose. Verified numerical defects are corrected; changes to +intended conventions require agreement on expected behavior and compatibility impact in the owning +issue. Preserving an existing output is not a reason to retain a verified defect. + +Shared maintenance automation prepares triage and review recommendations for maintainer approval. +It records the revision inspected and distinguishes metadata inspection, diff inspection, and +executed verification. Missing API or runner evidence is reported as missing evidence. Automated +recommendations do not post comments or reviews, apply labels, approve runs, close items, merge, +publish, or write to library branches. Code and documentation changes use the owning repository's +pull-request process.