# Contributing
## Basic Information
This project is developed with very limited resources, so we put a strong focus on maintainability, consistency.
This document explains the contribution guidelines and expectations for pull requests.
### What to contribute
You can contribute in several ways:
- Report bugs and request features via GitHub Issues.
- Implement features or bug fixes via pull requests.
- Improve documentation, comments, or examples.
If you are unsure whether a change is desirable, open an issue first and ask.
### Project Policy
- Code itself is technical debt
We consider "every line of code to be technical debt".
Our default is to avoid adding code unless it is clearly necessary.
Code that does not provide clear value will not be merged.
We aggressively delete unused or low-value code to keep the codebase small and understandable.
For external pull requests, the most important point in the description is "why is it necessary to merge this change".
- Consistency over local optimality
We value a consistent software design more than isolated perfectness in a small area.
Inconsistent software is hard to understand and maintain and small inconsistencies accumulate and become serious long-term obstacles.
We prefer solutions that fit well with existing patterns and architecture, even if another design might be locally “more correct.”
In PR reviews, a discussion like the following may happen:
> “This feature looks useful, but it is inconsistent with the existing implementation. To keep the project coherent, we would need to almost rewrite it from scratch.
> We have two options:
> 1. You (the contributor) rewrite it to match the existing style and architecture.
> 2. I (the maintainer) rewrite it from scratch.
> Which do you prefer?”
Please don’t be surprised by this kind of feedback.
It’s aligned with our policy of keeping the codebase consistent.
- Prefer loosely coupled software
To reduce maintenance cost, we try to design loosely coupled components.
Please minimize dependencies between modules/crates, clear interfaces and boundaries, avoid changes that tightly couple previously independent parts of the system.
If your contribution introduces new cross-module dependencies, please be prepared to discuss why they are necessary.
- Keep pull requests small
We prefer small and focused PRs.
Please avoid PRs that touch many unrelated parts of the code.
Because some users depend on individual crates in this repository, so please do not create a single PR that spans multiple crates with unrelated changes.
If possible, split changes into separate PRs per crate or per logical unit of work.
Small PRs are easier to review, easier to revert, and less risky to merge.
---
## Pull Requests
We generally follow this workflow for contributions.
### 1. Open an issue
If you want to add or change code, please open an issue first:
- Describe the problem or feature request clearly.
- Explain why this change is needed (use cases, impact, etc.).
- If you already have an approach in mind, describe it briefly so we can discuss.
This helps ensure that your work aligns with the project’s direction before you invest your time.
If necessary for troubleshooting, please provide the debug log output when reporting the issue.
```sh
RUST_LOG=debug ml-cellar init
```
### 2. Implementation
After we agree on the direction in the issue discussion:
1. Fork this repository.
2. Create a new branch for your work.
3. Implement the change according to the agreed design and the policies above:
- Minimize added code where possible.
- Preserve consistency with the existing code style and architecture.
- Keep the PR as small and focused as you reasonably can.
### 3. Run tests
Run the full test suite locally before pushing:
```sh
cargo test --all
```
Ensure all tests pass and there are no clippy warnings:
```sh
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
```
### 4. Update documentation
If your change impacts architecture or public interfaces, then please update the relevant documentation.
### 5. Commit messages & opening a pull request
We recommend using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
They make it easy to generate categorized changelogs, for example using tools like [git-cliff](https://github.com/orhun/git-cliff).
```
feat(interface): add loss function
```
If your change breaks existing interfaces, mark it as a breaking change using `!`:
```
feat(interface)!: change function name from function_a() to function_b()
```
You can use the following types:
- `feat` — for new features
- `fix` — for bug fixes
- `chore` — for maintenance tasks, build changes, tooling, etc.
When you open the PR, please include:
- A short summary of the change.
- A motivation section explaining why the change is needed.
- A brief note on testing (what you ran and what passed).
- If relevant, a note about breaking changes or migration steps.
### 6. Responding to review comments
After you open a pull request:
- Maintainers may leave comments or request changes.
- Please respond to all comments:
- Update the code where appropriate.
- Reply if you disagree, explaining your reasoning or asking for clarification.
We may ask you to:
- Simplify or reduce the amount of code.
- Align with existing patterns for consistency.
- Split a large PR into smaller ones.
Once the review feedback is addressed and the PR is in line with the project policies, it can be merged.
---
## Thank you
Contributing under these constraints can be a bit strict, but it helps keep the project healthy in the long run.
We truly appreciate the time and effort you put into reading these guidelines and contributing under them.