Docs: Add contribution file to the project (#38)

# Goal

As outlined in issue #32, the aim of this PR is to create a
`CONTRIBUTING.md` file that provides detailed guidance for developers on
how to contribute effectively to the project.

Fix #32

---------

Co-authored-by: Pierre Camilleri <[email protected]>

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing Guidelines
+
+Thank you for taking the time to contribute to the `fr-format` project! Your help is greatly appreciated.
+
+## How to Contribute ?
+
+We welcome all forms of contributions: 
+
+* Reporting issues or suggesting improvements
+* Improving and adding documentation
+* Enhancing code
+
+In all cases, ensure you are working with the latest version of the project.
+
+For more details, follow the sections below.
+
+## Reporting issues or suggesting improvements
+
+If you encounter a bug or have a suggestion, please:
+
+1. Check if the issue already exists in the [Github Issues section](https://github.com/datagouv/fr-format/issues).
+2. Provide a detailed issue report is very appreciated!\
+   Including:\
+              - A clear description of the problem or suggestion.\
+              - Steps to reproduce the bug (if applicable).\
+              - Any relevant logs or screenshots.
+
+If you want to propose a new format, please verify:
+
+1. that it does not already exists in the [list of available formats](./docs/formats.md)
+2. that the new format is relevant. The scope of fr-format is _exclusively_ specifically French formats. 
+
+See the [specific section](#implementing-a-new-french-format) below for guidelines on implementing a new format.
+
+## Improving and adding documentation
+
+All documentation files are located in [docs folder](./docs).\
+Also, if you identify areas for improvement in the documentation, please contribute!
+
+## Enhancing code
+
+### Project setup and code style guidelines
+
+See the [developper documentation](./docs/dev_documentation.md) for details on how to setup the project, and the code style guidelines.
+
+### Adding features or fixing bugs
+
+1. Create a fork of the repository.
+2. Implement your changes and test them :
+   - Run `make test` to execute tests.
+   - Use `make lint` to ensure your code follows the project's style guidelines.
+3. Document your changes:
+   - Provide a clear explanation in your pull request description.
+   - Add comments to your code if necessary.
+   - If your changes include new features, please document them in the ["./docs"](./docs) folder. New formats' documentation are automatically generated (see below).
+4. Finally, submit your pull request.
+
+### Implementing a new French format
+
+After verification, these are the steps to add it:
+
+1. Create a new file in `src/frformat/formats` to implement the format validation logic. The most generic format interface is `CustomFormat`, but look out for helper functions (e.g. in `set_format.py`) for specific cases. (You can take examples from the existing code.)
+2. Write tests for it!
+3. Fix Linting problems running `make lint-fix`.
+4. Import the format inside `./src/frformat/__init__` and add it to the `all_formats` list. 
+5. Run `make generate-docs` to update the format documentation. 
+
+## License
+
+By contributing to `fr-format`, you agree that your contributions will be licensed under the project's [open-source license](./LICENSE.md).
+
+Thank you for your contribution!

README.md

@@ -31,4 +31,10 @@ For better performance on big amounts of data, use in conjunction with numpy.
 
 ## Available formats
 
-Check out [this file](./docs/formats.md) for a list of available formats.
+Check out [this documentantion](./docs/formats.md) that lists all available formats.
+
+## Contributing
+
+Found a bug, want to propose a feature or a new format? See the [contribution guidelines](./CONTRIBUTING.md) on how to proceed!
+
+

docs/dev_documentation.md

@@ -0,0 +1,46 @@
+# Developper documentation
+
+This documentation is aimed at developpers that want to contribute or maintain fr-format.
+
+## Setup the project
+
+This project uses [poetry](https://python-poetry.org/) as a dependency manager. 
+
+Please follow these steps to contribute effectively to the project:
+
+1. Clone the project repository and navigate to `fr-format` folder.
+2. Insure you have Poetry installed by running `poetry --version`. If not, [install Poetry](https://pypi.org/project/poetry/).
+3. Check your Python version matches the required version specified in `pyproject.toml`.
+4. Run `poetry install --all-groups` to create a virtual environment and install all dependencies.
+5. Activate the virtual environment using `poetry shell`.
+
+## Task Runner
+
+The project uses a Makefile to manage common tasks. The command `make` or `make help` will show available tasks.
+
+## Code Style Guidelines
+
+`fr format` project uses the following linting and formatting dependencies:
+
+- [black](https://black.readthedocs.io/en/stable/)
+- [isort](https://pycqa.github.io/isort/)
+- [flake8](https://flake8.pycqa.org/)
+- [pyright](https://github.com/microsoft/pyright)
+
+These tools are can be installed with the `linting` group (`poetry install --with linting`).
+
+## Publishing process
+
+This project uses git tags associated with [continuous deployment](../.github/workflows/publish.yaml) to manage version bumps and Pypi publication. 
+
+Here is the full process to publish a new version :
+
+- Check which version to publish. We use [semantic versionning](https://semver.org/).
+- `git checkout main && git pull`
+- Update [CHANGELOG.md](../CHANGELOG.md) and push changes on main.
+- `git tag vX.Y.Z`
+- `git push --tags`
+- Check that CD pipeline has succeeded
+
+
+

docs/formats.md

@@ -18,3 +18,5 @@
 | Region | Nom de région | Vérifie les régions françaises valides pour un Code Officiel Géographique donné |
 | Siren | SIREN | Check french SIREN number validity, but does not check if SIREN number exists. |
 | Siret | SIRET | Check french SIRET number validity, but does not check if SIRET number exists. |
+
+[If you want to add a new French Format, click here!](../CONTRIBUTING.md#implementing-a-new-french-format)

pyproject.toml

@@ -6,7 +6,7 @@ authors = [
   "Pierre Camilleri <[email protected]>",
   "Amélie Rondot"
 ]
-license = "AGPL-3.0"
+license = "MIT"
 readme = "README.md"
 packages = [
   {include = "frformat", from = "src"}
@@ -18,12 +18,17 @@ python-stdnum = "^1.19"
 shapely = "^2.0.2"
 
 
+[tool.poetry.group.linting]
+optional = true
+
 [tool.poetry.group.linting.dependencies]
 black = "^23.12.1"
 isort = "^5.13.2"
 pyright = "^1.1.369"
 flake8 = "^7.0.0"
 
+[tool.poetry.group.dev]
+optional = true
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.4.4"

utils/formats_template.md.jinja

@@ -5,3 +5,5 @@
 {% for validator in validators %}
 | {{ (validator.class_name) }} | {{ (validator.name) }} | {{ (validator.description) }} |
 {% endfor %}
+
+[If you want to add a new French Format, click here!](../CONTRIBUTING.md#implementing-a-new-french-format)