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. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..0726b0b91 --- /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 section and\ + follow its approval requirements before publishing. + +## Generated code + +Changes to optimizer definitions require regenerating `src/optimagic/algorithms.py`\ +through the existing hook. 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.