diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bc0a8f1 --- /dev/null +++ b/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! diff --git a/README.md b/README.md index 980749c..3c98498 100644 --- a/README.md +++ b/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! + + diff --git a/docs/dev/README.md b/docs/dev/README.md deleted file mode 100644 index f358a8f..0000000 --- a/docs/dev/README.md +++ /dev/null @@ -1,50 +0,0 @@ - -# Developping tools - -## Dependency manager - -This project uses [poetry](https://python-poetry.org/) as a dependency -manager. - -``` -pip install poetry -``` - -## Developping environment - -### Linting - -Install developper tools with : - -``` -poetry install --with linting -``` - -Code style is checked continuously and enforced with -[`black`](https://github.com/psf/black), -[`isort`](https://pypi.org/project/isort/), -[`flake8`](https://pypi.org/project/flake8/) and -[`pyright`](https://github.com/microsoft/pyright). - -### Task Runner - -The project uses a Makefile to manage common tasks. The command `make` will show available tasks. - -## 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 - - - diff --git a/docs/dev_documentation.md b/docs/dev_documentation.md new file mode 100644 index 0000000..56dc3cc --- /dev/null +++ b/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 + + + diff --git a/pyproject.toml b/pyproject.toml index 0599af5..d72bf67 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ authors = [ "Pierre Camilleri <22995923+pierrecamilleri@users.noreply.github.com>", "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"