From 9d7becd03f529a3bd58836c3c836a864dd8f1204 Mon Sep 17 00:00:00 2001 From: Pierre Camilleri Date: Tue, 21 Jan 2025 10:46:50 +0100 Subject: [PATCH] Udpdates during review --- CONTRIBUTING.md | 93 ++++++++++++++------------------------- README.md | 8 +++- docs/dev/README.md | 50 --------------------- docs/dev_documentation.md | 46 +++++++++++++++++++ pyproject.toml | 5 +++ 5 files changed, 92 insertions(+), 110 deletions(-) delete mode 100644 docs/dev/README.md create mode 100644 docs/dev_documentation.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1cd3898..efbcda2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,88 +9,63 @@ We welcome all forms of contributions,they are highly encouraged: * Submitting Pull Requests (Enhancing code, Improving or adding documentation) * Reporting Issues or suggesting improvements +In all cases, ensure you are working with the latest version of the project. + For more details, follow the sections below. -### Submitting Pull Requests +## 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: -#### Enhancing code +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. -Please follow these important steps to contribute effectively to the project: +See the [specific section](#implementing-a-new-french-format) below for guidelines on implementing a new format. -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` to create a virtual environment and install all dependencies. -5. Activate the virtual environment using `poetry shell`. -6. Use the `Makefile` for predefined tasks. Run `make help` to see available commands. +## Enhancing code -##### Adding features or fixing bugs +### Project setup and code style guidelines -At first, ensure you are working with the latest version of the project: `git pull origin main`. +See the [developper documentation](./docs/dev_documentation.md) for details on how to setup the project, and the code style guidelines. -After verification, follow these steps: +### Adding features or fixing bugs -1. Create a new branch for your feature or fix: `git checkout -b feature-name`. +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. - -6. Finally, submit your pull request and tag relevant contributors for review . + - Add comments to your code if necessary. +4. Finally, submit your pull request. -##### Suggesting a new french format (Main feature) - -Before adding a new format, please verify at first these two points before creating the pull request appropriate to this feature: - -1. Check the [list of available formats](./docs/formats.md) to ensure it doesn't already exist. -2. Be sure that the new format is relevant, meaningful and specifically French. +### Implementing a new French format After verification, these are the steps to add it: -1. Create a file to store validated data values(If the data list is large) -2. Create a second one to implement the format validation logic. (You can take examples from the existing code) -3. Test it! -4. Fix Linting problems running `make lint-fix`. -5. Import the format inside `./src/frformat/__init__`. -6. Add it to `all_formats` list. -7. Run `make generate-docs` to update the format documentation. -The aim of this step is to save all formats inside one table to be more clear for users. +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. -#### Improving and adding documentation +## Improving and adding documentation All documentation files are located in [docs folder](./docs).\ If your changes include complex logic or functionality, add clear and concise doc comments to explain them. -Also, if you identify areas for improvement in the [README file](./docs/dev/README.md), other documentation files, or even files without existing documentation where an explanation would add value, please contribute, it's highly encouraged! - -**Note**: If you are adding a new french format to the project, remember to run `make generate-docs` to update the documentation and refresh the list of all available formats. - -### Reporting Issues or suggesting improvements - -If you encounter a bug or have a suggestion, please: - -1. Ensure you are using the latest version of the project and verify if updating fixes your issue first. -2. Check if the issue already exists in the [Github Issues section](https://github.com/datagouv/fr-format/issues) (please do not open a duplicate one !). -3. Provide a detailed issue report is very appreciate!\ - Including:\ - - A clear description of the problem or suggestion.\ - - Steps to reproduce the bug (if applicable).\ - - Any relevant logs or screenshots. - -## Code Style Guidelines - -`fr format` projevt 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 installed automatically when you run `poetry install` after forking the project.\ -Before submitting your code, run `make lint` to check for linting issues and fix them using `make lint-fix`. +Also, if you identify areas for improvement in the documentation, please contribute! ## License -By contributing to `fr-format`, you agree that your contributions will be licensed under the project's open-source license: MIT. +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 ! +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..b6fd28c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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"