From 4e5f87686f565709580d8acf395f1c77c8ea3185 Mon Sep 17 00:00:00 2001 From: James Gallagher Date: Tue, 15 Aug 2023 10:02:22 +0100 Subject: [PATCH 1/6] update contributing file --- CONTRIBUTING.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 62838aec..3195d9d8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,55 @@ Before you contribute a new feature, consider submitting an Issue to discuss the ## How to Contribute Changes -First, fork this repository to your own GitHub account. Create a new branch that describes your changes (i.e. `line-counter-docs`). Push your changes to the branch on your fork and then submit a pull request to `develop` branch of this repository. +First, fork this repository to your own GitHub account. Click "fork" in the top corner of the `supervision` repository to get started: + +![Forking the repository](https://media.roboflow.com/fork.png) + +![Creating a repository fork](https://media.roboflow.com/create_fork.png) + +Then, run `git clone` to download the project code to your computer. + +Move to a new branch using the `git checkout` command: + +```bash +git checkout -b +``` + +The name you choose for your branch should describe the change you want to make (i.e. `line-counter-docs`). + +Make any changes you want to the project code, then run the following commands to commit your changes: + +```bash +git add . +git commit -m "Your commit message" +git push -u origin main +``` + +This project utilizes the [pre-commit](https://pre-commit.com/) tool to maintain code quality and consistency. Before submitting a pull request or making any commits, it is important to run the pre-commit tool to ensure that your changes meet the project's guidelines. + +To run the pre-commit tool, follow these steps: + +1. Install pre-commit by running the following command: `poetry install`. It will not only install pre-commit but also install all the deps and dev-deps of project + +2. Once pre-commit is installed, navigate to the project's root directory. + +3. Run the command `pre-commit run --all-files`. This will execute the pre-commit hooks configured for this project against the modified files. If any issues are found, the pre-commit tool will provide feedback on how to resolve them. Make the necessary changes and re-run the pre-commit command until all issues are resolved. + +4. You can also install pre-commit as a git hook by execute `pre-commit install`. Every time you made `git commit` pre-commit run automatically for you. + +Then, go back to your fork of the `supervision` repository, click "Pull Requests", and click "New Pull Request". + +![Opening a pull request](https://media.roboflow.com/open_pr.png) + +Click "compare across forks" and select your fork from the dropdown menu. Then, click "Create pull request". + +On the next page, review your changes then click "Create pull request": + +![Configuring a pull request](https://media.roboflow.com/create_pr_submit.png) + +Next, write a description for your pull request, and click "Create pull request" again to submit it for review: + +![Submitting a pull request](https://media.roboflow.com/write_pr.png) When creating new functions, please ensure you have the following: @@ -49,4 +97,4 @@ So far, **there is no types checking with mypy**. See [issue](https://github.com ## ๐Ÿงช tests -[`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests. +[`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests. \ No newline at end of file From b0643562804cb7de049c427bc5e3a8dd8c83e68f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 15 Aug 2023 09:03:17 +0000 Subject: [PATCH 2/6] =?UTF-8?q?fix(pre=5Fcommit):=20=F0=9F=8E=A8=20auto=20?= =?UTF-8?q?format=20pre-commit=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3195d9d8..889576ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,7 +60,7 @@ To run the pre-commit tool, follow these steps: 4. You can also install pre-commit as a git hook by execute `pre-commit install`. Every time you made `git commit` pre-commit run automatically for you. -Then, go back to your fork of the `supervision` repository, click "Pull Requests", and click "New Pull Request". +Then, go back to your fork of the `supervision` repository, click "Pull Requests", and click "New Pull Request". ![Opening a pull request](https://media.roboflow.com/open_pr.png) @@ -97,4 +97,4 @@ So far, **there is no types checking with mypy**. See [issue](https://github.com ## ๐Ÿงช tests -[`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests. \ No newline at end of file +[`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests. From 9167101e9269f4cd4207e3b696eeecbc134e6900 Mon Sep 17 00:00:00 2001 From: James Gallagher Date: Tue, 15 Aug 2023 10:05:46 +0100 Subject: [PATCH 3/6] add develop branch guidance --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 889576ce..3c4b6d65 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,7 +64,7 @@ Then, go back to your fork of the `supervision` repository, click "Pull Requests ![Opening a pull request](https://media.roboflow.com/open_pr.png) -Click "compare across forks" and select your fork from the dropdown menu. Then, click "Create pull request". +Make sure the `base` branch is `develop` before submitting your PR. On the next page, review your changes then click "Create pull request": From a2b8cf50d699bc053c68f9cf8ba7e5c635b33443 Mon Sep 17 00:00:00 2001 From: James Gallagher Date: Tue, 15 Aug 2023 13:21:50 +0100 Subject: [PATCH 4/6] add docs --- CONTRIBUTING.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c4b6d65..490ec6c2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,12 +80,22 @@ When creating new functions, please ensure you have the following: 2. Unit tests for the function. 3. Examples in the documentation for the function. 4. Created an entry in our docs to autogenerate the documentation for the function. -5. Please share google colab with minimal code to test new feature or reproduce PR whenever it is possible. Please ensure that google colab can be accessed without any issue. +5. Please share a Google Colab with minimal code to test new feature or reproduce PR whenever it is possible. Please ensure that Google Colab can be accessed without any issue. + +When you submit your Pull Request, you will be asked to sign a Contributor License Agreement (CLA) by the `cla-assistant` GitHub bot. We can only respond to PRs from contributors who have signed the project CLA. All pull requests will be reviewed by the maintainers of the project. We will provide feedback and ask for changes if necessary. PRs must pass all tests and linting requirements before they can be merged. +## ๐Ÿ“ documentation + +The `supervision` documentation is stored in a folder called `docs`. The project documentation is built using `mkdocs`. + +To run the documentation, install the project requirements with `poetry install dev`. Then, run `mkdocs serve` to start the documentation server. + +You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/). + ## ๐Ÿงน code quality We provide two handy commands inside the `Makefile`, namely: @@ -93,7 +103,11 @@ We provide two handy commands inside the `Makefile`, namely: - `make style` to format the code - `make check_code_quality` to check code quality (PEP8 basically) -So far, **there is no types checking with mypy**. See [issue](https://github.com/roboflow-ai/template-python/issues/4). +So far, **there is no type checking with mypy**. See [issue](https://github.com/roboflow-ai/template-python/issues/4). + +All new functions and classes in `supervision` should include docstrings. This is a prerequisite for any new functions and classes to be added to the library. + +`supervision` adheres to the [Google Python docstring style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods). Please refer to the style guide while writing docstrings for your contribution. ## ๐Ÿงช tests From 5bd78d11cc752af51b59b705ac6723c13d88aa7b Mon Sep 17 00:00:00 2001 From: James Gallagher Date: Thu, 17 Aug 2023 11:28:14 +0100 Subject: [PATCH 5/6] add license section --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 490ec6c2..94342adb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -112,3 +112,7 @@ All new functions and classes in `supervision` should include docstrings. This i ## ๐Ÿงช tests [`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests. + +## ๐Ÿ“„ license + +By contributing, you agree that your contributions will be licensed under an [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). \ No newline at end of file From 3a6de392fcc71bc0bdcb7756eff8fac9f5e5dfb9 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 17 Aug 2023 10:28:26 +0000 Subject: [PATCH 6/6] =?UTF-8?q?fix(pre=5Fcommit):=20=F0=9F=8E=A8=20auto=20?= =?UTF-8?q?format=20pre-commit=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94342adb..c6e32d8c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -115,4 +115,4 @@ All new functions and classes in `supervision` should include docstrings. This i ## ๐Ÿ“„ license -By contributing, you agree that your contributions will be licensed under an [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md). \ No newline at end of file +By contributing, you agree that your contributions will be licensed under an [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md).