diff --git a/.github/workflows/pre-commit.yaml b/.github/workflows/pre-commit.yaml index 237df8af..e5b96b43 100644 --- a/.github/workflows/pre-commit.yaml +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 6f9f0378..a530a2e3 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..6a89682d --- /dev/null +++ b/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/)`/` — 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/): + ``` + [optional scope]: + + + + + ``` + +### Valid types for `` 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). +- ``: 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 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. +- ``: 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 "" | conventional-commit-lint` and make sure the exit code is `0`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0ac89d75..3310a386 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index 008136fd..7a915ab6 100644 --- a/README.md +++ b/README.md @@ -81,14 +81,18 @@ Both EngiBench and EngiOpt are open source projects and we welcome contributions ### Installation -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.