chore(commits): introduce conventional commits

.github/workflows/pre-commit.yaml

@@ -1,3 +1,4 @@
+---
 # https://pre-commit.com
 # This GitHub Action assumes that the repo contains a valid .pre-commit-config.yaml file.
 name: pre-commit
@@ -7,7 +8,7 @@ on:
     branches: [main]
 
 permissions:
-  contents: read # to fetch code (actions/checkout)
+  contents: read  # to fetch code (actions/checkout)
 
 jobs:
   pre-commit:
@@ -16,3 +17,20 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
       - uses: pre-commit/action@v3.0.1
+
+  conventional-commits:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history needed for commit comparison
+
+      - name: Fetch main branch ref (not available in PR context)
+        run: git fetch origin main:main
+
+      - name: Lint all commit messages within the PR
+        run: |
+          python -m pip install --upgrade pip
+          pip install git+https://gitlab.ethz.ch/sis/tools/conventional-commit-lint.git@0.9.0
+          git log --pretty="commit %h%n%B%x00" --no-merges ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }} | conventional-commit-lint

.pre-commit-config.yaml

@@ -1,5 +1,7 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
+---
+default_install_hook_types: [pre-commit, commit-msg]
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
@@ -25,6 +27,10 @@ repos:
         args:
           - --skip=*.ipynb,engibench/problems/airfoil/pyopt_history.py
           - --ignore-words-list=mor,le,te,ure,varn
+  - repo: https://gitlab.ethz.ch/sis/tools/conventional-commit-lint
+    rev: 0.9.0
+    hooks:
+      - id: conventional-commit-lint
   - repo: local
     hooks:
       - id: pyright

AGENTS.md

@@ -0,0 +1,83 @@
+# AGENTS instructions
+
+Developer relevant documentation is kept in `README.md` as well as `docs/tutorials/new_problem.md`.
+In the following, steps to set up the environment, run tests, build docs and follow the PR workflow are given.
+
+## Project structure
+
+- [engibench/core.py](engibench/core.py) — `Problem` base class, `OptiStep`, `ObjectiveDirection`
+- [engibench/constraint.py](engibench/constraint.py) — constraint system
+- [engibench/problems/](engibench/problems/)`<name>/` — one subpackage per problem, each exports a single `Problem` subclass
+- [engibench/utils/](engibench/utils/) — container runtimes, slurm, CLI helpers, problem discovery
+- [tests/](tests/) — pytest suite; [test_problem_implementations.py](tests/test_problem_implementations.py)
+  parametrizes over all builtin problems
+- [docs/](docs/) — Sphinx (MyST), built with `cd docs && make dirhtml`
+
+## Setup of a local virtual environment
+
+- Run `python -m venv .venv` to create a virtual environment.
+- `. .venv/bin/activate` to activate the environment.
+- The project itself, including all dependencies is installed in development mode by `pip install -e ".[dev]"`.
+
+## Setup of pre-commit hooks
+
+- Installation of pre-commit is done by `pip install pre-commit`.
+- Setup of the hooks: `pre-commit install`.
+
+## Running tests / Code quality assurance
+
+- To run the tests, use `pytest`.
+- Lint: `ruff check`.
+- Check formatting by `ruff format --check`.
+- Check typing consistency with `mypy .`.
+
+## Building documentation
+
+- Documentation can be built locally using `cd docs` followed by `make dirhtml`
+  as described in [docs/README.md](./docs/README.md).
+  `make dirhtml` will essentially call `sphinx-build . _build`.
+
+## Pull request guidelines
+
+- Follow the PR guidance in [CONTRIBUTING.md](CONTRIBUTING.md).
+- Add tests when adding new features or fixing bugs.
+- For commits, comply with [conventional commit messages](https://www.conventionalcommits.org/) (see next section)
+
+## Conventional commits
+
+- For commits, use the structure of [conventional commit messages](https://www.conventionalcommits.org/):
+  ```
+  <type>[optional scope]: <description>
+
+  <optional body>
+
+  <optional footer(s)>
+  ```
+
+### Valid types for `<type>` based on the changed files obtained by `git status` and
+  the changes obtained by `git diff --staged`:
+  - `feat`: A new feature
+  - `fix`: A bug fix
+  - `docs`: Documentation only changes, i.e. inside the directory [docs](docs)
+  - `style`: Code style changes (i.e. reformatting due to a new version of [ruff](https://docs.astral.sh/ruff/))
+  - `refactor`: Code change that neither fixes a bug nor adds a feature
+  - `perf`: Performance improvements
+  - `test`: Adding or updating tests in the [tests](tests) directory
+  - `build`: Changes to build system or dependencies, i.e. [pyproject.toml](pyproject.toml)
+  - `ci`: Changes to CI configuration [.github/](.github)
+  - `chore`: Other changes that don't modify files in the directories [engibench](engibench), [docs](docs) or [tests](tests)
+- `optional scope`: Optional but recommended. Describes the changed component or module name (enclosed in parentheses).
+- `<description>`: Must follow the following rules:
+   - MUST be lowercase (except proper nouns)
+   - MUST be imperative mood ("add feature" not "added feature" or "adding feature")
+   - MUST be max 72 characters
+   - MUST NOT end with a period
+- `<optional body>`: Optional but welcome. Is separated from the subject line (1st line)
+  by a blank line and explains WHAT changed and WHY but not HOW. It is wrapped at 72 chars.
+- `<optional footer(s)>`: Used for breaking changes. In this case it starts with `BREAKING CHANGE: `
+  followed by a description the breaking change and how to migrate
+
+### Validation of the commit message
+
+- Use [conventional-commit-lint](https://gitlab.ethz.ch/sis/tools/conventional-commit-lint) as follows:
+  `echo "<commit_message>" | conventional-commit-lint` and make sure the exit code is `0`.

CONTRIBUTING.md

@@ -16,6 +16,13 @@ EngiBench aims to simplify research and adoption of ML for engineering design. W
 * Ensure your PR description clearly explains the problem and your solution. Reference the related issue if applicable.
 * Verify your code passes all required checks (see our [PR template](https://github.com/IDEALLab/EngiBench/blob/main/.github/PULL_REQUEST_TEMPLATE.md) for details).
 
+### Commit Message Format
+
+We follow the rules of [conventional commit](https://www.conventionalcommits.org).
+This will be checked in our CI by [conventional-commit-lint](https://gitlab.ethz.ch/sis/tools/conventional-commit-lint).
+A [commit-msg hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) is provided by our
+[.pre-commit-config.yaml](./.pre-commit-config.yaml).
+
 ### Documentation or Cosmetic Changes
 
 * Open a PR for fixes such as typos, formatting, or minor documentation updates.

README.md

@@ -81,14 +81,18 @@ Both EngiBench and EngiOpt are open source projects and we welcome contributions
 
 ### Installation
 <!-- start dev-install -->
-To install EngiBench for development, clone the repo, install the pre-commit hooks, and install all dev dependencies:
+To install EngiBench for development, clone the repo, install the [pre-commit](https://pre-commit.com/) hooks, and install all dev dependencies:
 
-```bash
+```sh
 git clone git@github.com:IDEALLab/EngiBench.git
 cd EngiBench
 pre-commit install
 pip install -e ".[dev]"
 ```
+
+Our pre-commit config also includes a hook to ensure compliance with [conventional commit](https://www.conventionalcommits.org)
+formatting (see [CONTRIBUTING.md](./CONTRIBUTING.md#commit-message-format)).
+
 Also worth installing [`ruff`](https://docs.astral.sh/ruff/) and [`mypy`](https://www.mypy-lang.org/) in your editor as we are checking the code style and type safety on our CI.
 <!-- end dev-install -->