Contribute to Loggia¤

Foreword¤

First off, thank you for taking the time to contribute!

It's worth mentioning that the purpose of this document is to provide you with a set of general guidelines and not strict rules: nothing is set in stone and we welcome contributions about these contributing guidelines as well :-)

TL;DR¤

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 pull request before it can be merged. If you are familiar with GitHub (and Git), branching and opening a pull request or an issue... then you should be able to start contributing right away.

It is strongly advised to contact the project owner(s) before working on implementing a new feature or making any kind of large code refactoring.

Contributors must agree to the following:

material without explicit copyright assignment will be assigned to ManoMano
apart from a few identified exceptions, material must be licensed under the ISC license; in all cases, a license is mandatory.

Tooling¤

We recommended that you use pdm to manage your Python development environment.

You can check the list of available developers commands with pdm run --list

Coding style¤

Follow the project's conventions and tooling.

Contact the contributors if you need help with tooling.

Run the linter locally with pdm run lint and the formatters with pdm run fmt

Documentation¤

We consider documentation as important as code. Substantial contribution must always come with exhaustive documentation.

Run the documentation locally with pdm run docs-serve

Tests¤

Application and contributions should be tested and push for the highest quality standard.

Run the tests locally with pdm run test or pdm run test-cov

There is a tox configuration to run the tests against all supported Python versions, and with different packages installed.

Git¤

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

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}/${REPONAME}
cd ${REPONAME}

Create a topic branch where changes will be done.
```
git checkout -b ${TOPIC_BRANCH}
```
Commit the changes in logical and incremental chunks and use interactive rebase when needed.

In your commit message, 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...'
```
Push the topic branch to the remote forked repository.
```
git push origin ${TOPIC_BRANCH}
```
Open a Pull request to the upstream repository with a clear title and description.
Once the PR has been merged, the topic branch can be removed from the local fork.
```
git branch -d ${TOPIC_BRANCH}
git push origin --delete ${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.

Issues¤

If you find a bug that you don't know how to fix, please create an issue:

use a clear and descriptive title
give a step by step explanation on how to reproduce the problem
include as many details as possible, even ones that may seem irrelevant; gists are a good way to include large amount of context and information
describe what was already tried to fix the problem

This document is adapted from ManoMano Guidelines