#  Contributing to QUEENS
Thank you very much for your willingness to contribute to QUEENS! We strongly believe in the synergy effect of developing and using QUEENS together as a community.

We invite you to share your methodological contributions to both deterministic and probabilistic models and analyses, such as:
- Parameter studies and identification
- Sensitivity analysis
- Surrogate modeling
- Uncertainty quantification
- Bayesian inverse analysis
- Optimization

In addition to methodological contributions, we also greatly appreciate infrastructure contributions that help ensure QUEENS runs smoothly and efficiently. These include, but are not limited to, bug fixes and improvements related to
- Code quality
- Performance
- User interface
- Benchmarking
- [Testing](https://www.github.com/queens-py/queens/blob/main/tests/README.md)
- [Tutorials](https://queens-py.github.io/queens/tutorials.html)
- [Documentation](https://www.github.com/queens-py/queens/blob/main/doc/README.md)

We welcome all types of code contributions, irrespective of size and complexity.

> Note: If you're unsure whether your contribution fits within the QUEENS framework, don't hesitate to ask the community by starting a [discussion](https://github.com/queens-py/queens/discussions) or by opening an [issue](https://github.com/queens-py/queens/issues) 

## Contributing on GitHub
###  Issues
Issues are generally used to remind or inform yourself or others about certain things in the
software. We use them to report bugs, start a feature request, or plan tasks. In case you have a
general question, please refer to [GitHub Discussions](https://github.com/queens-py/queens/discussions).

To create an issue, select one of our templates and provide a detailed description. We use labels
to organize our issues, so please label issues with the mandatory labels
- `status:` label
- `topic:` label
- `type:` label

More [labels](https://github.com/queens-py/queens/labels) can of course be assigned if they
contribute to categorizing the issue.

Before you open a new issue, please check within the existing issues if your bug has
already been reported. Opening an issue is a valid contribution on its own and does not mean you
have to solve them yourself.


###  Pull requests

#### 1. Install QUEENS in developer mode
Install QUEENS as described in the [README.md](https://github.com/queens-py/queens/blob/main/README.md).
For contributions, use the Pixi development environment and expose your local clone inside it:
<!---installation_develop marker, do not remove this comment-->
```bash
pixi install --environment dev
pixi run -e dev install-editable
```
<!---installation_develop marker, do not remove this comment-->

#### 2. Configure our git-hooks
To help you write style-compliant code, we use the [pre-commit](https://pre-commit.com/) package to manage all our git
hooks automatically. Please run:
```
pre-commit install --install-hooks --overwrite
pre-commit install --hook-type commit-msg
```

#### 3. Code development

##### Coding style
QUEENS code follows the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style. Non-compliant code
will lead to failing CI pipelines and will therefore not be merged.
The code checks are conducted with [Pylint](https://pylint.org/),
[isort](https://github.com/PyCQA/isort), and [Black](https://github.com/psf/black).
Compliance with [Google style docstrings](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings)
is checked with [ruff](https://github.com/astral-sh/ruff).
Complete and meaningful docstrings are required as they are used to generate the
[documentation](https://www.github.com/queens-py/queens/blob/main/doc/README.md).

##### QUEENS coding conventions
Like every codebase, QUEENS follows some project-specific coding conventions. Below is a list of common ones:
- Use `pathlib.Path` objects instead of strings to handle paths and directories.
- If relative paths within the QUEENS source are needed, use the [relative_path_from_queens_source](https://www.github.com/queens-py/queens/blob/main/src/queens/utils/path.py#L24) function.
- Decorate the init method of QUEENS objects with the `log_init_args` decorator from [src/queens/utils/logger_settings.py](https://www.github.com/queens-py/queens/blob/main/src/queens/utils/logger_settings.py#L248). This automatically logs the arguments passed to the init.
- We only allow disabling pylint warnings for specific lines, not for entire files. If you disable warnings, please use the long pylint description, not just the code.

##### Changing dependencies
QUEENS declares dependencies in `pyproject.toml` and locks the Pixi environments in `pixi.lock`.
For a short overview of the available environments, see the
[requirements FAQ](https://www.github.com/queens-py/queens/blob/main/doc/source/faqs/requirements.md). This section describes how to add, remove, or
update dependencies.

When changing dependencies, keep the PEP-style dependency declarations and the Pixi declarations in
sync:
- Runtime dependencies belong in `[project].dependencies` and the matching
  `[tool.pixi.feature.base]` dependency section.
- Optional runtime dependencies belong in `[project.optional-dependencies]` and a matching
  `[tool.pixi.feature.<name>]` section.
- Development-only tools belong in `[dependency-groups].dev` and the matching
  `[tool.pixi.feature.dev]` dependency section.
- In Pixi sections, use `dependencies` for Conda packages and `pypi-dependencies` for packages that
  must be installed from PyPI or a Git source.
- Do not add test, linting, formatting, documentation, or release tooling to the base runtime
  dependencies unless it is actually needed by QUEENS at runtime.

After editing `pyproject.toml`, run the dependency integrity check. The same check is installed as a
pre-commit hook and also runs in CI:
```bash
pixi run -e dev pre-commit run check-pyproject-dependency-integrity --files pyproject.toml
```

If dependency declarations changed, refresh the lockfile and commit it together with
`pyproject.toml`:
```bash
pixi lock
git add pyproject.toml pixi.lock
```

The CI pipeline checks this as well: if dependency-relevant sections in `pyproject.toml` changed and
`pixi lock --check --dry-run` would update `pixi.lock`, the code quality job fails. Before opening
or updating a pull request, it is useful to verify the lockfile locally:
```bash
pixi lock --check --dry-run
```

Finally, reinstall or update the affected Pixi environment and run a focused test or smoke check:
```bash
pixi install --environment dev
pixi run -e dev install-editable
pixi run -e dev pytest
```

##### Commit messages
Please provide meaningful commit messages based on the
[Conventional Commits guidelines](https://www.conventionalcommits.org/en/v1.0.0/).
These are verified by the commit-msg hook (managed by [commitizen](https://github.com/commitizen-tools/commitizen)).

#### 4. Test your code
New code must be tested. Please also make sure that all existing tests pass by running `pytest` in
your source directory. For further information, see our [testing README.md](https://www.github.com/queens-py/queens/blob/main/tests/README.md).

#### 5. Submit a pull request
Please use the available pull request template and fill out all sections of the template.
When you have submitted a pull request and the CI pipeline passes, it will be reviewed.
Once your pull request is approved, there is a 24h waiting time (business days only) until the branch is merged into the
main branch by the QUEENS maintainers. This ensures that the community has a chance to have a final look over the changes.
This rule can be circumvented if and only if:
- All the active maintainers approve the pull request.
- The pull request is labeled as a quickfix by one of the maintainers and approved. Examples for this are one-liners, typos or urgent fixes that are time-critical.