Development¤

We want to make contributing straightforward and easy for everyone. As such and unless otherwise stated we will use the traditional Github fork and pull workflow: any commit must be made to a feature/topic branch in a local fork and submitted via a merge request before it can be merged. It is strongly advised to open a discussion or an issue before working on implementing a new feature or making any kind of large code refactoring.

Issues and merge requests should be in English.

Git¤

Make sure you have a GitHub account. The main branch should be considered as the production/deploy branch.

Forking workflow¤

Extensive information can be found in this excellent forking workflow tutorial.

In a nutshell:

Fork the repository and clone it locally.

git clone https://github.com/${USERNAME}/firefighter-incident
cd firefighter-incident

Create a topic branch where changes will be done.
```
git checkout -b ${MY_TOPIC_BRANCH}
```
Commit the changes in logical and incremental chunks and use interactive rebase when needed. In your commit messages, make sure to: - use the present tense - use the imperative mood - limit the first line to 72 characters - reference any associated issues and/or PRs (if applicable)
```
git commit -am 'Add new feature...'
```
You may loosely follow conventional commits if you want to.
Add test if needed & make sure the test suite and various linters are passing.
Push the topic branch to the remote forked repository.
```
git push origin ${MY_TOPIC_BRANCH}
```
Open a Pull Request to merge your code and its documentation. The earlier you open a merge request, the sooner you can get feedback.
Verify the test suite is passing in the CI & verify if the pipeline is green.

Once the PR has been merged, the topic branch can be removed from the local fork.

git branch -d ${MY_TOPIC_BRANCH}
git push origin --delete ${MY_TOPIC_BRANCH}

Syncing a fork with its upstream¤

This is used to keep a local fork up-to-date with the original upstream repository.

Connect the local to the original upstream repository.

git remote add upstream https://github.com/${USERNAME}/${REPONAME}

Checkout, fetch and merge the upstream master branch to the local one.
```
git checkout main
git fetch upstream
git merge upstream/master
```
Push changes to update to remote forked repository.
```
git push
```

See GitHub help for more information.

Dev tooling¤

Check all available commands using pdm run --list.

Formatting¤

We use black. You can run pdm run fmt or black . in the project root to format every file.

pdm run fmt

This is the equivalent of running black . in the project root.

Import sorting managed by ruff.

Linting¤

ruff, pylint and mypy are configured.

pdm run lint-ruff

pdm run lint-pylint

This is the equivalent of running pylint --django-settings-module=firefighter.settings <our_sources> in the project root.

Note

We are progressively disabling Pylint checks that are implemented by ruff.

pdm run lint-mypy

This is the equivalent of running mypy <our_sources> in the project root.

Warning

The lint checks won't pass, as they are still some issues/false positives that needs to be fixed.

Testing¤

pdm run tests

This is the equivalent of running pytest tests in the project root.

Warning

The testing coverage is still very low.

Documentation¤

pdm run docs-serve

This is the equivalent of running mkdocs serve in the project root. // TODO Pre-commit hook

Conventions¤

Code style¤

We loosely follow the PEP8 style guide and Google's Python Style Guide.

Use your best judgement when deciding whether to break the rules.

Imports¤

Import sorting is managed by ruff. Absolute imports are enforced.

Docstrings¤

We use Google-style docstrings.

You can link to other classes, methods, functions, or modules by using the mkdocstrings cross-reference syntax:

With a custom title:
[`Object 1`][full.path.object1]

With the identifier as title:
[full.path.object2][]

You can cross-reference to the Python standard library and Django objects.