mirror of
https://github.com/fhswf/aki_prj23_transparenzregister.git
synced 2025-04-24 13:52:33 +02:00
74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
# CONTRIBUTING.md: Contribution guidelines
|
|
|
|
## Dev Setup
|
|
|
|
- [Install Python 3.11](https://www.python.org/downloads/release/python-3115/)
|
|
- [Install Poetry](https://python-poetry.org/docs/#installation)
|
|
- [Install GiT](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
|
- [Configure GiT](https://support.atlassian.com/bitbucket-cloud/docs/configure-your-dvcs-username-for-commits/)
|
|
- [Generate an SSH Key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) & [Add SSH Key to GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)
|
|
- [Clone the Project (IDE Specific)](https://docs.github.com/de/repositories/creating-and-managing-repositories/cloning-a-repository)
|
|
- [Install the python Project](https://python-poetry.org/docs/basic-usage/#installing-dependencies)
|
|
- Install pre-commit - see below
|
|
|
|
## Repository structure
|
|
|
|
- **`src/aki_prj23_transparenzregister`**:
|
|
- This sub-folder / `package` contains several subdirectories:
|
|
- `ai`:
|
|
- Houses AI models and pipelines, including NER and sentiment analysis.
|
|
- `config`:
|
|
- Contains configuration files such as database connection strings and model files.
|
|
- `models`:
|
|
- Stores data models.
|
|
- `ui`:
|
|
- Manages the user interface and dash interface.
|
|
- `utils`:
|
|
- Contains general tooling functions, including database access and other miscellaneous functions.
|
|
|
|
- **tests**:
|
|
- Test files organized in a mirrored structure of the 'src' folder. Please at least import every python file you
|
|
add.
|
|
Please Try to test every function with a test that compares with an example result. If that is not possible it
|
|
would be best to find a big consensus that only limited testing is required.
|
|
|
|
## Code style
|
|
|
|
We defined to use the following formats:
|
|
|
|
- Whitespace Formatting by [Black](https://github.com/psf/black)
|
|
- Docstrings Style see the examples provided
|
|
by [sphinx napoleon](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) Types in the
|
|
docstrings are optional but should be consistent per module.
|
|
- Import Order by [isort](https://pycqa.github.io/isort/)
|
|
- Strict Typing of function headers see the examples provided by
|
|
the [mypy](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html) documentation.
|
|
- The generell linting is done by ruff but since ruff is a reimplementation of ruff of many different linters the old
|
|
documentations are still valid.
|
|
- Ruff can be executed with the `ruff .` command. May errors are auto-fixable with `ruff --fix .` if they are straight
|
|
forward changes.
|
|
|
|
## Language
|
|
|
|
We decided to use english on everything close to code but will write longer texts that are not close to the code in
|
|
german.
|
|
|
|
## Pre-Commit Usage
|
|
- [Install pre-commit](https://pre-commit.com/#install): `pre-commit install --install-hooks -t post-checkout -t post-merge -t pre-commit`
|
|
|
|
- the following code format rules are so enforced:
|
|
- Whitespace formatting:
|
|
- Python-[Black](https://github.com/psf/black)
|
|
- leading whitespace in all files
|
|
- Auto format: yaml, toml, ini
|
|
- Import norm by:
|
|
- [isort](https://pycqa.github.io/isort/)
|
|
- absolut module path
|
|
- Validation:
|
|
- yaml, toml, json, xml
|
|
- Secret detection
|
|
- python norms ([pep8](https://peps.python.org/pep-0008/))
|
|
with [ruff](https://github.com/astral-sh/ruff)
|
|
- type checking with ([mypy](https://github.com/python/mypy))
|
|
- for more information read [Python Pre-Commit](https://pre-commit.com/)
|