From 2a21345345418050983034d85c0b0a4cfa573ce0 Mon Sep 17 00:00:00 2001 From: timmens Date: Mon, 19 Oct 2026 14:16:19 +0200 Subject: [PATCH 1/4] Clarify pull request contribution checklist --- .../PULL_REQUEST_TEMPLATE/pull_request_template.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index 5a1fce7d5..29f507d43 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -3,9 +3,12 @@ Reference the issue or discussion, if there is any. Provide a description of your proposed solution. -### Todo +### Checklist -- [ ] Target the right branch and pick an appropriate title. -- [ ] Put `Closes #XXXX` in the first PR comment to auto-close the relevant issue once - the PR is accepted. This is not applicable if there is no corresponding issue. -- [ ] Any steps that still need to be done. +- [ ] I have read the [contributor guide](https://optimagic.readthedocs.io/en/latest/development/how_to_contribute.html). +- [ ] I have described any additional validation I performed (e.g., manual checks, numerical comparisons, or benchmarks) and any remaining validation gaps. +- [ ] I have added or updated tests for changed behavior. +- [ ] I have updated documentation for user-facing changes. +- [ ] I have linked any issues this PR resolves using `Closes #XXXX`. +- [ ] I have described any substantial AI assistance and how I checked the result. +- [ ] I have selected the appropriate base branch and described any remaining work. From c4d0e313deebe3596c9617f863fa8aa466c31886 Mon Sep 17 00:00:00 2001 From: timmens Date: Tue, 20 Oct 2026 21:26:14 +0200 Subject: [PATCH 2/4] Add project guidance for coding agents --- AGENTS.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..e5933fddf --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,31 @@ +## Environment + +- Use Pixi for Python environments and development tasks +- Tasks and environments are defined in `pyproject.toml` +- Run `pixi task list` to discover available commands + +## Git + +- Run `prek install` once to enable pre-commit checks + +## Tests + +- Run affected tests while iterating (`pixi run tests `) +- Use `pixi run tests-fast` for broader checks (it excludes slow and JAX tests) +- For cross-cutting changes, run the full suite (`pixi run tests`) in a Pixi + environment with the required dependencies + +## Task-specific guidance + +Consult the relevant sections of the documentation for your task: + +- Contribution workflow: [contributor guide](docs/source/development/how_to_contribute.md). +- Code changes: [style guide](docs/source/development/styleguide.md). +- Typing and public interfaces: [EP-02](docs/source/development/ep-02-typing.md). +- GitHub activity: read the contributor guide's AI-use and review sections and\ + follow their approval requirements before publishing. + +## Generated code + +Changes to optimizer definitions require regenerating `src/optimagic/algorithms.py`\ +through the existing hook. From cbb4f8d56b98069e5ca03d11ef9e144248a88e64 Mon Sep 17 00:00:00 2001 From: timmens Date: Wed, 21 Oct 2026 00:14:43 +0200 Subject: [PATCH 3/4] Clarify contribution workflows and AI use --- AGENTS.md | 4 +- docs/source/development/how_to_contribute.md | 267 ++++++++++++------- 2 files changed, 176 insertions(+), 95 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e5933fddf..0726b0b91 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,8 +22,8 @@ Consult the relevant sections of the documentation for your task: - Contribution workflow: [contributor guide](docs/source/development/how_to_contribute.md). - Code changes: [style guide](docs/source/development/styleguide.md). - Typing and public interfaces: [EP-02](docs/source/development/ep-02-typing.md). -- GitHub activity: read the contributor guide's AI-use and review sections and\ - follow their approval requirements before publishing. +- GitHub activity: read the contributor guide's AI-use section and\ + follow its approval requirements before publishing. ## Generated code diff --git a/docs/source/development/how_to_contribute.md b/docs/source/development/how_to_contribute.md index a281e4af5..29cf885c5 100644 --- a/docs/source/development/how_to_contribute.md +++ b/docs/source/development/how_to_contribute.md @@ -4,130 +4,211 @@ ## 1. Intro -We welcome and greatly appreciate contributions of all forms and sizes! Whether it's -updating the documentation, adding small extensions, or implementing new features, every -effort is valued. +We welcome your ideas and expertise, whether you are getting started with optimagic or +bring years of experience in optimization and scientific software. There are many ways +to contribute, from suggesting features and reporting bugs to improving documentation, +adding tests, and contributing code. -For substantial changes, please contact us in advance. This allows us to discuss your -ideas and guide the development process from the beginning. You can start a conversation -by posting an issue on GitHub or by emailing [janosg](https://github.com/janosg). +Our preferred starting point for new features and substantial improvements is a +well-developed issue. It helps us understand the need, agree on a design, and plan the +implementation together. -To get familiar with the codebase, we recommend checking out our -[issue tracker](https://github.com/optimagic-dev/optimagic/issues) for some immediate -and clearly defined tasks. +When a well-developed issue leads to a merged change, we credit the issue author as a +contributor in the corresponding [release notes](changes.md), alongside those who +implement the change. -## 2. Before you start +The situations below explain how to get started and which sections of this guide to +read. -Once you've decided to contribute, please review the {ref}`style_guide` (see the next -page) to ensure your work aligns with the project's coding standards. +- **You would like a new feature.** Describe your use case and the behavior you would + find helpful. See [Writing an issue](#contributing-issues). +- **You noticed a bug.** Tell us what happened, what you expected, and how to reproduce + it. See [Writing an issue](#contributing-issues). +- **You want to improve documentation or tests.** Small, focused improvements are + welcome as pull requests. Follow [Preparing a change](#contributing-preparing) and + [Opening and updating a pull request](#contributing-prs). For substantial changes, + start with an issue to agree on the scope and approach. +- **You want to implement an issue or contribute a code improvement.** Small, + well-defined changes are welcome as pull requests. For larger changes, first agree on + the scope and approach with the maintainers on the issue. Then follow + [Preparing a change](#contributing-preparing) and + [Opening and updating a pull request](#contributing-prs). -We manage new features through Pull Requests (PRs). Contributors work on their local -copy of optimagic, modifying and extending the codebase there, before opening a PR to -propose merging their changes into the main branch. +If you use AI tools, read [Using AI tools](#contributing-ai) before posting on GitHub. -Regular contributors gain push access to unprotected branches, which simplifies the -contribution process (see Notes below). +If you are looking for a starting point, browse our +[issue tracker](https://github.com/optimagic-dev/optimagic/issues) for tasks that +interest you. You can also work through the documentation and examples and suggest ways +to make them clearer or easier to follow. -## 3. Step-by-step guide +(contributing-issues)= -1. Fork the [optimagic repository](https://github.com/optimagic-dev/optimagic/). This - action creates a copy of the repository with write access for you. +## 2. Writing an issue -```{note} -For regular contributors: **Clone** the [repository](https://github.com/optimagic-dev/optimagic/) to your local machine and create a new branch for implementing your changes. You can push your branch directly to the remote optimagic repository and open a PR from there. -``` +Search the issue tracker for related discussions first. An existing issue may already +address your question, and additional examples or evidence can help move it forward. +When opening a new issue, choose the template that best fits your contribution. + +### Feature requests + +Help us understand the problem you want to solve: + +- Describe your use case and why the change would help. +- Explain what you currently do and where that approach falls short. +- Describe the behavior you would like, with a small example if useful. + +If you have ideas for an API or implementation, include them so we can discuss the +design together. + +### Bug reports + +Give us enough information to reproduce and investigate the problem: + +- A small, runnable example, or clear steps to reproduce the behavior. +- What you expected and what actually happened, including relevant error messages. +- Your optimagic and Python versions, operating system, and relevant dependency + versions. + +For numerical problems, include the relevant inputs and results so we can assess the +behavior. + +### Larger improvements + +For substantial changes to code, documentation, or tests, describe the current +limitation, intended outcome, affected area, and proposed scope. Share any approach or +tradeoffs you have considered. Agree on the scope and approach with the maintainers +before starting implementation. -1. Clone your forked repository to your disk. This is where you'll make all your - changes. +For example, an illustrative documentation issue might say: "In the algorithm-selection +guide, I could not tell how to choose between two derivative-free methods. An example +comparing when each is useful would help." A proposal for reorganizing several guides +could outline the new structure and explain which reader needs it addresses. -1. Open your terminal and execute the following commands from the root directory of your - local optimagic repository: +If you use AI tools to prepare or submit an issue, consult +[Using AI tools](#contributing-ai) before posting. Once you are ready to implement an +agreed change, continue with [Preparing a change](#contributing-preparing). + +(contributing-preparing)= + +## 3. Preparing a change + +### Set up your working copy + +1. Fork the [repository](https://github.com/optimagic-dev/optimagic/), clone your fork, + and create a branch for your change. Contributors who already have push access can + use a branch in the main repository. + +1. Install [Pixi](https://github.com/prefix-dev/pixi) for Python environments and + development tasks, and [prek](https://github.com/j178/prek) for pre-commit checks. + Prek is installed separately from Pixi. + +1. From the repository root, enable the Git hooks: ```console $ prek install ``` - This activates pre-commit hooks for linting and style formatting. +Pixi automatically selects the environment for the tasks below and creates it when +needed. Use `-e ` to target a particular test environment. Tasks and +environments are defined in `pyproject.toml`. To discover available commands, run: - ```{note} - `prek` is not managed by pixi and must be installed globally. You can find - installation instructions at [github.com/j178/prek](https://github.com/j178/prek). - ``` +```console +$ pixi task list +``` - You can then run the test suite with: +### Follow the relevant guides - ```console - $ pixi run tests - ``` +- For code and tests, follow the [style guide](styleguide.md). +- For typing and public interfaces, consult [EP-02](ep-02-typing.md). +- For documentation, follow the documentation section of the + [style guide](styleguide.md). - which installs the development dependencies and runs pytest. To run the type checker, - use: +Keep the change focused on its purpose. The current tool configuration is in +`pyproject.toml` and `.pre-commit-config.yaml`. - ```console - $ pixi run ty - ``` +### Check your change - To see all available pixi tasks, run: +Run tests for the behavior you changed while iterating. For example: - ```console - $ pixi task list - ``` +```console +$ pixi run tests tests/optimagic/optimization/test_optimize.py +``` + +Include relevant slow tests before opening a PR. For broader checks, use +`pixi run tests-fast`; it excludes slow and JAX tests on every platform. For +cross-cutting changes, run the full suite with `pixi run tests` in an environment with +the required dependencies. The named Linux test environments in `pyproject.toml` include +JAX and PETSc. + +For changes affecting typing, run: -1. Implement your fix or feature. Use git to add, commit, and push your changes to the - remote repository. For more on git and how to stage and commit your work, refer to - these - [online materials](https://effective-programming-practices.vercel.app/git/staging/objectives_materials.html). - -1. Contributions are validated in two main ways. We run a comprehensive test suite to - ensure compatibility with the existing codebase and employ - [pre-commit hooks](https://effective-programming-practices.vercel.app/git/pre_commits/objectives_materials.html) - to maintain quality and adherence to our style guidelines. Opening a PR (see below) - triggers optimagic's - [Continuous Integration (CI)](https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration) - workflow, which runs the full test suite, pre-commit hooks, and other checks on a - remote server. - - You can also run the test suite locally for - [debugging](https://effective-programming-practices.vercel.app/debugging/pdbp/objectives_materials.html). - - With prek installed, linters run before each commit. Commits are rejected if any - checks fail. Note that some linters may automatically fix errors by modifying the - code in-place. Remember to re-stage the files after such modifications. - -```{tip} -Skip the next paragraph if you haven't worked on the documentation. +```console +$ pixi run ty ``` -1. Assuming you have updated the documentation, verify that it builds correctly. Run: +With hooks enabled, formatting and lint checks run before each commit. Some checks +modify files automatically; review and re-stage those changes before committing again. - ```console - $ pixi run build-docs - ``` +### Documentation changes - This command builds the HTML documentation, saving all files in the `docs/build/html` - directory. You can view the documentation with your preferred web browser by opening - `docs/build/html/index.html` or any other file. Similar to the online documentation, - you can navigate to different pages simply by clicking on the links. +Build the documentation and inspect the affected pages: -1. Once all tests and hooks pass locally, push your changes to your forked repository - and create a pull request through GitHub: Go to the Github repository of your fork. A - banner on your fork's GitHub repository will prompt you to open a PR. +```console +$ pixi run build-docs +``` - ```{note} - Regular contributors with push access can directly push their local branch to the remote optimagic repository and initiate a PR from there. - ``` +Open `docs/build/html/index.html` in your browser to view the result. The build executes +notebooks, so allow time for their examples to run. + +### Generated code + +Changes affecting optimizer definitions, `src/optimagic/algorithms.py`, or `.tools/` +trigger a hook that regenerates `src/optimagic/algorithms.py` from the optimizer +definitions. This hook requires `uv` on your path. Include the regenerated file in your +change. + +(contributing-prs)= + +## 4. Opening and updating a pull request + +Prepare a focused PR that makes your change easy to assess: + +- Use a descriptive title, select the appropriate base branch, and follow the + [PR template](https://github.com/optimagic-dev/optimagic/blob/main/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md). +- Explain the problem, your solution, and any remaining work. Link the relevant issue; + use `Closes #XXXX` when the PR resolves it. +- Describe the checks you ran, their results, and any remaining validation gaps. +- Identify the author of a well-developed issue that led to the change so they can + receive contributor credit. + +If you use AI tools, read [Using AI tools](#contributing-ai) before publishing or +updating the PR. Include the requested description of substantial AI assistance. + +Push your branch to your fork, or to the main repository if you have push access, and +open the PR against optimagic. Automated CI checks cover tests, formatting, typing, and +documentation. Monitor the results, investigate failures, and explain any unresolved +limitations. + +Request a maintainer review when the PR is ready. Respond to feedback with changes or an +explanation, and keep the description current as the PR develops. A maintainer will +merge the approved change. + +(contributing-ai)= + +## 5. Using AI tools - Follow the steps outlined in the optimagic - [PR template](https://github.com/optimagic-dev/optimagic/blob/main/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md) - to describe your contribution, the problem it addresses, and your proposed solution. +We welcome carefully prepared contributions, including AI-written code and text. +Contributors should check what they submit for accuracy and relevance and be able to +explain it. Review generated code and test the behavior it changes, following +[Preparing a change](#contributing-preparing) and the [style guide](styleguide.md). - Opening a PR initiates a complete CI run, including the `pytest` suite, linters, code - coverage checks, doctests, and building the HTML documentation. Monitor the CI - workflow status on your PR page and make necessary modifications to your code based - on the results, iterating until all tests pass. +We ask contributors to briefly describe substantial AI use in their PR, including how +they used the tools and checked the result. The PR template includes a reminder. -1. Request a review from one of the main contributors once all CI tests pass. Address - any feedback or suggestions by making the necessary changes and committing them. +Autonomous agent activity on GitHub requires explicit prior maintainer approval for the +proposed activity. This includes opening issues or PRs, posting comments, and submitting +reviews. Contributors remain responsible for the content and actions of agents they use. -1. After your PR is approved, one of the main contributors will merge it into - optimagic's main branch. +Maintainers prioritize relevant, carefully prepared submissions and may close or remove +submissions at their discretion. Feedback is provided as time allows. Repeated +low-quality or unsolicited activity may lead to restrictions on participation. From 7d9385a1847eaf5759bc5462ae7fc677b76042ba Mon Sep 17 00:00:00 2001 From: timmens Date: Mon, 2 Nov 2026 17:18:15 +0100 Subject: [PATCH 4/4] Address contributor guidance review feedback --- AGENTS.md | 13 ++++--------- docs/source/development/how_to_contribute.md | 20 +++++--------------- 2 files changed, 9 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0726b0b91..099b16160 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,14 +6,14 @@ ## Git -- Run `prek install` once to enable pre-commit checks +- If pre-commit checks do not run when committing, run `prek install` ## Tests - Run affected tests while iterating (`pixi run tests `) - Use `pixi run tests-fast` for broader checks (it excludes slow and JAX tests) -- For cross-cutting changes, run the full suite (`pixi run tests`) in a Pixi - environment with the required dependencies +- For changes to shared code used across multiple modules, run the full suite + (`pixi run tests`) ## Task-specific guidance @@ -23,9 +23,4 @@ Consult the relevant sections of the documentation for your task: - Code changes: [style guide](docs/source/development/styleguide.md). - Typing and public interfaces: [EP-02](docs/source/development/ep-02-typing.md). - GitHub activity: read the contributor guide's AI-use section and\ - follow its approval requirements before publishing. - -## Generated code - -Changes to optimizer definitions require regenerating `src/optimagic/algorithms.py`\ -through the existing hook. + follow its guidance before publishing. diff --git a/docs/source/development/how_to_contribute.md b/docs/source/development/how_to_contribute.md index 29cf885c5..32748fc4b 100644 --- a/docs/source/development/how_to_contribute.md +++ b/docs/source/development/how_to_contribute.md @@ -69,9 +69,6 @@ Give us enough information to reproduce and investigate the problem: - Your optimagic and Python versions, operating system, and relevant dependency versions. -For numerical problems, include the relevant inputs and results so we can assess the -behavior. - ### Larger improvements For substantial changes to code, documentation, or tests, describe the current @@ -79,11 +76,6 @@ limitation, intended outcome, affected area, and proposed scope. Share any appro tradeoffs you have considered. Agree on the scope and approach with the maintainers before starting implementation. -For example, an illustrative documentation issue might say: "In the algorithm-selection -guide, I could not tell how to choose between two derivative-free methods. An example -comparing when each is useful would help." A proposal for reorganizing several guides -could outline the new structure and explain which reader needs it addresses. - If you use AI tools to prepare or submit an issue, consult [Using AI tools](#contributing-ai) before posting. Once you are ready to implement an agreed change, continue with [Preparing a change](#contributing-preparing). @@ -135,10 +127,8 @@ $ pixi run tests tests/optimagic/optimization/test_optimize.py ``` Include relevant slow tests before opening a PR. For broader checks, use -`pixi run tests-fast`; it excludes slow and JAX tests on every platform. For -cross-cutting changes, run the full suite with `pixi run tests` in an environment with -the required dependencies. The named Linux test environments in `pyproject.toml` include -JAX and PETSc. +`pixi run tests-fast`; it excludes slow and JAX tests on every platform. For changes to +shared code used across multiple modules, run the full suite with `pixi run tests`. For changes affecting typing, run: @@ -205,9 +195,9 @@ explain it. Review generated code and test the behavior it changes, following We ask contributors to briefly describe substantial AI use in their PR, including how they used the tools and checked the result. The PR template includes a reminder. -Autonomous agent activity on GitHub requires explicit prior maintainer approval for the -proposed activity. This includes opening issues or PRs, posting comments, and submitting -reviews. Contributors remain responsible for the content and actions of agents they use. +We strongly prefer human-written communication on GitHub. You may use AI tools and +agents to help draft issues, PR descriptions, comments, and reviews. You remain +responsible for the accuracy, relevance, and quality of what you post. Maintainers prioritize relevant, carefully prepared submissions and may close or remove submissions at their discretion. Feedback is provided as time allows. Repeated