diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 83cb6947..0a068605 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -1,5 +1,5 @@ name: Bug report -description: Report reproducible incorrect behavior in ecosystem policy or tooling +description: Report one reproducible Backtest defect title: "[Bug]: " labels: - "type: bug" @@ -10,7 +10,9 @@ body: - type: markdown attributes: value: | - Search existing issues first. Do not disclose suspected vulnerabilities here. + Search existing issues first and report one problem here. + Read [CONTRIBUTING.md](https://github.com/ml4t/backtest/blob/main/CONTRIBUTING.md). + Report suspected vulnerabilities through the private security link instead. - type: dropdown id: library attributes: @@ -50,13 +52,16 @@ body: id: expected attributes: label: Expected behavior + description: >- + For a numerical defect, state the intended definition and expected result. An earlier + output alone does not establish correctness. validations: required: true - type: textarea id: reproduction attributes: label: Minimal reproduction - description: Provide the smallest complete example and error output. + description: Provide the smallest complete public API or user workflow example and error output. validations: required: true - type: dropdown @@ -78,3 +83,12 @@ body: description: State the observable conditions that demonstrate the issue is resolved. validations: required: true + - type: textarea + id: ai_assistance + attributes: + label: AI assistance + description: >- + State whether AI tools helped prepare this report and which parts they produced. + Write "None" if none. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index a1d07662..cf8be9a3 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -3,6 +3,6 @@ contact_links: - name: Security vulnerability url: https://github.com/ml4t/backtest/security/advisories/new about: Report suspected vulnerabilities privately. - - name: Usage questions - url: https://github.com/orgs/ml4t/discussions - about: Ask questions that do not describe a defect or requested change. + - name: Usage documentation + url: https://www.ml4trading.io/docs/backtest/user-guide/ + about: Read the Backtest user guide for usage instructions and examples. diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml index d060f5a8..252c4c53 100644 --- a/.github/ISSUE_TEMPLATE/documentation.yml +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -7,6 +7,11 @@ labels: - "status: needs-triage" - "compatibility: none" body: + - type: markdown + attributes: + value: | + Search existing issues and report one documentation problem. + Read [CONTRIBUTING.md](https://github.com/ml4t/backtest/blob/main/CONTRIBUTING.md). - type: dropdown id: library attributes: @@ -53,3 +58,12 @@ body: label: Acceptance criteria validations: required: true + - type: textarea + id: ai_assistance + attributes: + label: AI assistance + description: >- + State whether AI tools helped prepare this report and which parts they produced. + Write "None" if none. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml index ca17225c..ce6eabe2 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 and describe one change. + Read [CONTRIBUTING.md](https://github.com/ml4t/backtest/blob/main/CONTRIBUTING.md). - type: dropdown id: library attributes: @@ -64,3 +69,12 @@ body: label: Acceptance criteria validations: required: true + - type: textarea + id: ai_assistance + attributes: + label: AI assistance + description: >- + State whether AI tools helped prepare this request and which parts they produced. + Write "None" if none. + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 0d924318..ea4bbac0 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,18 +2,34 @@ Closes # +Keep this PR focused on one issue. Automated dependency updates and administrative metadata +changes may state that exception here instead of linking an issue. + ## Outcome Describe the user-visible or standards outcome. +## Bug regression evidence + +For a bug fix, exercise the affected public API or user workflow on both revisions. The test must +fail because of the defect on the base and pass with the fix. State "Not a bug fix" when this +section does not apply. + +- Base revision, command, and observed failure: +- Fix revision, command, and passing result: + ## Compatibility - [ ] No public compatibility impact - [ ] Compatibility impact is documented in the owning issue and migration guidance +For numerical changes, state the intended result and how it was checked independently of the old +output. If the definition, annualization, sign convention, or default changes, cite the decision in +the owning issue and describe the compatibility impact. + ## Verification -- [ ] Tests reproduce the prior failure or verify the requested behavior +- [ ] Bug regression fails on the base and passes with the fix, or this is not a bug fix - [ ] Ruff lint and format checks pass - [ ] `ty` passes - [ ] Test suite passes @@ -21,6 +37,13 @@ Describe the user-visible or standards outcome. - [ ] Strict MkDocs build passes when documentation is affected - [ ] Ecosystem qualification passes +List the commands actually run and their results. Explain any unchecked item. + +## AI assistance + +State whether AI tools helped produce the code, tests, documentation, or PR text, and identify the +parts they produced. Write "None" if none. Confirm that you reviewed and tested any AI-assisted work. + ## Documentation and release State the documentation, release notes, and patch-release work required after merge. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..2323d789 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,26 @@ +# Contributing to ml4t-backtest + +Read the [ML4T contribution policy](https://github.com/ml4t/ecosystem/blob/main/CONTRIBUTING.md) +before opening an issue or pull request. This guide identifies the Backtest-specific entry points. + +Search [existing issues](https://github.com/ml4t/backtest/issues) first. Report one problem per +issue. For a bug, include the affected package version, Python and operating-system versions, +expected and observed behavior, and a complete example that reproduces the result. Report suspected +vulnerabilities through the [private security process](SECURITY.md). + +Keep each pull request focused on one issue and include a closing reference such as `Closes #123`. +Automated dependency updates and administrative metadata changes do not need a separate issue. For +a bug fix, run a regression through the affected public API or user workflow against both the base +revision and the fix. Record both revisions, commands, and results in the pull request. The test +must fail because of the defect on the base and pass with the fix. Documentation changes need +documentation checks, not an artificial regression test. + +For numerical defects, establish the intended result independently of the old output. If the +definition, annualization, sign convention, or default changes, agree on the expected behavior in +the owning issue and describe the compatibility impact. + +Run the relevant commands in the [Development section](README.md#development) and the +[repository quality commands](AGENTS.md#quality-commands), then report the results. CI also checks +compatibility, security, parity, and package artifacts. State whether AI tools helped with the issue +or pull request and which parts they produced. Review and test that work yourself; be prepared to +explain it during review. diff --git a/README.md b/README.md index 8d76a7bb..950e8d19 100644 --- a/README.md +++ b/README.md @@ -476,6 +476,8 @@ Release-critical validation files are listed in [`validation/release_checks.txt`](validation/release_checks.txt). CI runs the supported gate set, including compatibility, security, parity, and artifact qualification. +Read [CONTRIBUTING.md](CONTRIBUTING.md) before filing an issue or pull request. + ## Known Limitations See [LIMITATIONS.md](LIMITATIONS.md) for documented assumptions: