mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2026-11-13 09:13:30 +01:00
Bobby NoelteandClaude Opus 5.5
dd41e5d57c
Additional changes Agents write a task plan to .scratch/<branch>/plan.md and self-review with code-review Agents fix hard violations, report judgement calls and rerun the self-review before every push Agents declare the review in a Self-review section of the pull request body Add the ai-self-review workflow and scripts/check_pr_self_review.py for pull requests into main Detect agents by Assisted-by or Anthropic Co-Authored-By trailers, body markers or the AI box Fail only on a missing Self-review section or a missing, malformed or stale Reviewed SHA Note an unticked AI-assisted box and malformed optional lines without failing Comment on the pull request how to fix a failure and update that one comment on later runs Show the same report in the job summary and accept Windows line endings in the body Skip dependabot and release pull requests Run on pull_request_target with the base branch's script, never pull request code Add the pull request template: the pr skill's sections plus Checklist and Self-review Require always valid optimization parameters in the energy-domain skill Require datetimeutil for date and time handling in new and changed code in AGENTS.md Require the Assisted-by trailer on agent commits in the commit-messages skill Add tests for the check in tests/test_ai.py Add GLOSSARY.md and the agent tracker docs in docs/agents/ Add decision record docs/adr/0001 with an ADR index in the docs toctree Document the workflow in docs/develop/ai.md and CONTRIBUTING.md Exclude docs/agents from Sphinx and PyMarkdown and ignore .scratch/ Document cz check instead of make gitlint for commit messages in docs/develop/ai.md Assisted-by: Claude Code (claude-opus-5-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
159 lines
6.6 KiB
Markdown
159 lines
6.6 KiB
Markdown
# Contributing to EOS
|
|
|
|
Thanks for taking the time to read this!
|
|
|
|
The `EOS` project is in early development, therefore we encourage contribution in the following ways:
|
|
|
|
## Documentation
|
|
|
|
Latest development documentation can be found at [Akkudoktor-EOS](https://akkudoktor-eos.readthedocs.io/en/latest/).
|
|
|
|
## Bug Reports
|
|
|
|
Please report flaws or vulnerabilities in the [GitHub Issue Tracker](https://github.com/Akkudoktor-EOS/EOS/issues) using the corresponding issue template.
|
|
|
|
## Ideas & Features
|
|
|
|
Issues in the [GitHub Issue Tracker](https://github.com/Akkudoktor-EOS/EOS/issues) are also fine
|
|
to discuss ideas and features.
|
|
|
|
You may first discuss the idea in the [Akkudoktor Forum](https://www.akkudoktor.net/forum/diy-energie-optimierungssystem-opensource-projekt/) before opening an issue.
|
|
|
|
## Code Contributions
|
|
|
|
We welcome code contributions and bug fixes via [Pull Requests](https://github.com/Akkudoktor-EOS/EOS/pulls).
|
|
To make collaboration easier, we require pull requests to pass code style, unit tests, and commit
|
|
message style checks.
|
|
|
|
### Setup development environment
|
|
|
|
Use `uv` to create the virtual environment and install development dependencies.
|
|
|
|
```bash
|
|
uv sync --locked --extra dev
|
|
```
|
|
|
|
Install make to get access to helpful shortcuts (documentation generation, manual formatting, etc.).
|
|
|
|
- On Linux (Ubuntu/Debian):
|
|
|
|
```bash
|
|
sudo apt install make
|
|
```
|
|
|
|
- On MacOS (requires [Homebrew](https://brew.sh)):
|
|
|
|
```zsh
|
|
brew install make
|
|
```
|
|
|
|
The server can be started with `make run`. A full overview of the main shortcuts is given by `make help`.
|
|
|
|
### Code Style
|
|
|
|
All code, comments, docstrings, identifiers and API field names are written in English.
|
|
|
|
Our code style checks use [`pre-commit`](https://pre-commit.com).
|
|
|
|
To run formatting automatically before every commit:
|
|
|
|
```bash
|
|
uv run --locked --extra dev pre-commit install
|
|
uv run --locked --extra dev pre-commit install --hook-type commit-msg --hook-type pre-push
|
|
```
|
|
|
|
Or run them manually:
|
|
|
|
```bash
|
|
uv run --locked --extra dev pre-commit run --all-files
|
|
```
|
|
|
|
### Static typing
|
|
|
|
Use `uv` on your `PATH` and the Python version pinned in `.python-version` (also used by the
|
|
pre-commit CI job). The supported typing entry points are:
|
|
|
|
```bash
|
|
make mypy
|
|
uv run --locked --extra dev pre-commit run mypy --all-files
|
|
```
|
|
|
|
Both run `uv run --locked --exact --extra dev python -m mypy --config-file pyproject.toml`.
|
|
CI runs the same local pre-commit hook. The environment includes all runtime dependencies and
|
|
development stubs from `uv.lock`, including the type information supplied by Pydantic and Pendulum.
|
|
`--locked` rejects an out-of-date lockfile instead of updating it, and `--exact` removes packages
|
|
outside the selected locked dependencies. Keep the Makefile and hook commands identical.
|
|
|
|
`[tool.mypy]` in `pyproject.toml` defines the policy for all of `src` and `tests`, targeting Python
|
|
3.13 and Linux. The hook always checks this complete scope, including on configuration-only changes.
|
|
It does not add the old mirror hook's `--ignore-missing-imports` or `--scripts-are-modules` defaults.
|
|
Only the existing per-module missing-import exceptions in `pyproject.toml` apply.
|
|
Incremental analysis is disabled because mypy 2.3.1 produces different Pendulum diagnostics with
|
|
warm and empty caches. Each entry point therefore performs a full analysis; this costs time but
|
|
keeps diagnostics independent of cache history without suppressing checks.
|
|
|
|
To regression-test the entry points run:
|
|
|
|
```bash
|
|
uv run --locked --extra dev pytest -q --finalize tests/test_typingmypytooling.py
|
|
```
|
|
|
|
This test creates a temporary project and a fresh locked development environment and hook/type-check
|
|
caches. It verifies valid Pydantic and Pendulum assignments, then deliberate type errors in both
|
|
`src` and `tests`, through Makefile, a configuration-only hook run, and the CI command. All probes
|
|
stay in the temporary project. It may download locked packages; set `UV_CACHE_DIR` to an empty
|
|
temporary directory as well to verify without a warm package cache.
|
|
|
|
### Tests
|
|
|
|
Use `pytest` to run tests locally:
|
|
|
|
```bash
|
|
uv run python -m pytest -vs --cov src --cov-report term-missing tests/
|
|
```
|
|
|
|
Group tests by the module or cohesive subsystem they exercise. Add regression tests to the
|
|
existing suite and use descriptive test classes to separate features, edge cases, and integration
|
|
scenarios. Scope feature-specific fixtures to their test class, especially autouse fixtures that
|
|
could change unrelated tests. Create another test file only for a distinct responsibility or
|
|
when the existing suite would become unwieldy; avoid one file per bug or pull request.
|
|
|
|
For example, keep time-window model tests in `tests/test_configabc.py`, measurement channels
|
|
and persistence in `tests/test_measurement.py`, and GENETIC0 parameter preparation in
|
|
`tests/test_genetic0params.py`. Keep provider-specific suites and unit/system tests separate.
|
|
When moving tests, verify that parametrized cases and fixture behavior are preserved with
|
|
`pytest --collect-only` and an execution of the affected suites.
|
|
|
|
### Commit message style
|
|
|
|
Our commit message checks use
|
|
[`commitizen`](https://commitizen-tools.github.io/commitizen/#pre-commit-integration). The checks
|
|
enforce the [`Conventional Commits`](https://www.conventionalcommits.org) commit message style.
|
|
|
|
You may use [`commitizen`](https://commitizen-tools.github.io/commitizen) also to create a
|
|
commit message and commit your change.
|
|
|
|
### AI-assisted contributions
|
|
|
|
You may use coding agents, but you are the author of what you propose and must review the complete
|
|
change yourself. Pull requests that an agent wrote or co-wrote are checked by CI:
|
|
|
|
- Every commit an agent wrote or co-wrote ends with the trailer
|
|
`Assisted-by: <tool> (<model id>)`, e.g. `Assisted-by: Claude Code (claude-opus-5-5)`.
|
|
- Tick the "AI-assisted" box in the pull request template.
|
|
- The pull request body ends with a `## Self-review` section from the agent's self-review. It names
|
|
the full SHA of the head commit it reviewed. Before every push, rerun the self-review and rewrite
|
|
the section, do not just edit the SHA; replace the body right after the push. Agents also add an
|
|
`Assisted-by:` line to the body, which marks the pull request as agent-assisted.
|
|
|
|
CI checks that the section is present and names the current head commit; other problems are
|
|
only noted. It cannot check the review itself. If the check fails, CI comments on the pull request
|
|
with what is wrong and how to fix it. See `docs/develop/ai.md` (AI-assisted development) for the
|
|
workflow and the exact format.
|
|
|
|
## Thank you!
|
|
|
|
And last but not least thanks to all our contributors
|
|
|
|
[](https://github.com/Akkudoktor-EOS/EOS/graphs/contributors)
|