From 37fd79a9eeea411b3f77b17844fac47c95c176dd Mon Sep 17 00:00:00 2001 From: Bernd Doser Date: Mon, 9 Sep 2024 16:17:04 +0200 Subject: [PATCH 1/7] add guidelines for contributing --- docs/contributing.md | 60 ++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + 2 files changed, 61 insertions(+) create mode 100644 docs/contributing.md diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..0fadaaa --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,60 @@ +# Contributing to Spherinator & HiPSter + +We welcome contributions to the Spherinator & HiPSter project. This document outlines the guidelines for contributing to the project. Don't worry about the length of this document. There are various ways to contribute to the project at different levels. Just get started, and we will help you through the process. Finally, all the guidelines and checks are in place to ensure the quality of the project. + +## Code of Conduct + +The project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Please read the code of conduct before contributing to the project. + +## Clear design and best practices + +The Python must adhere the [PEP8 Python coding style guide](https://peps.python.org/pep-0008/) for formatting and syntax. The [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) provides additional guidelines for writing clean and readable code. + +The Spherinator is using the design principles of the [PyTorch Lightning](https://lightning.ai/docs/pytorch/stable/) library. + +## Python dependencies + +The project uses [Poetry](https://python-poetry.org/) for dependency management. The dependencies are listed in the `pyproject.toml` file. To add new dependencies, use Poetry's `poetry add` command. It is recommended to keep the number of dependencies to a minimum. + +## Documentation + +Write docstrings for all public modules, functions, classes, and methods. Follow docstring conventions as outlined by [PEP 257](https://peps.python.org/pep-0257/). + +The user documentation is located in the `docs` directory and will be generated with [Sphinx](https://www.sphinx-doc.org/en/master/index.html) and hosted on [Read The Docs](https://spherinator.readthedocs.io/en/latest/index.html). + +## Testing + +The code is tested using [pytest](https://docs.pytest.org). All tests are located in the `tests` directory. + +## Continuous Integration + +GitHub Actions is used for continuous integration. The CI workflow is defined in [.github/workflows/python-package.yml](.github/workflows/python-package.yml). The CI workflow runs the tests and checks the code style and the code formatting on every push to the repository. + +## Code Formatting + +The Python code must be formatted with [black](https://black.readthedocs.io/en/stable/). +This can be done manually by running `black .` in the project directory or by installing the vscode extension `ms-python.black-formatter` and enabling the format on save option. +The CI workflow will check the code formatting and fail if the code is not formatted correctly. + +## Static code analysis + +The code is analyzed using [flake8](https://flake8.pycqa.org/en/latest/). + +## Pull requests + +The project uses the [GitHub flow](https://guides.github.com/introduction/flow/) to manage pull requests. + +1. Create a fork of the repository. Although you can create a branch in the main repository, it is recommended to create a fork for better isolation. +2. Create a branch in your fork. Let the branch name be descriptive of the changes you are making. +3. Make the changes in the branch. +4. Create a pull request from your branch to the main repository. +5. Check if all the checks are passing. If not, fix the issues and push the changes to the branch. +6. The pull request will be reviewed by the maintainers. The review process may involve multiple iterations of changes and reviews. +7. Please keep the branch up to date with the main repository by rebasing it on the main branch if necessary. +8. Once the pull request is approved, it will be merged into the main repository. + +## Issues + +If you find a bug or have a feature request, please create an issue in the [GitHub issue tracker](https://github.com/HITS-AIN/Spherinator/issues). + +Thank you for contributing to the Spherinator & HiPSter project! diff --git a/docs/index.md b/docs/index.md index 518ad97..852774b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,4 +15,5 @@ The documentation is under construction and not yet complete. For more informati installation.md training.md hipster.md +contribution.md ``` From 48b9a9d6fd5fda165d05e63989f098bb3b13d0a7 Mon Sep 17 00:00:00 2001 From: Bernd Doser Date: Tue, 10 Sep 2024 11:05:06 +0200 Subject: [PATCH 2/7] flake8 fail if any issue found --- .flake8 | 3 ++- .github/workflows/python-package.yml | 8 ++------ 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/.flake8 b/.flake8 index 10b08c8..4b930ae 100644 --- a/.flake8 +++ b/.flake8 @@ -1,4 +1,5 @@ [flake8] exclude = .git, .venv* max-line-length = 120 -max-complexity = 10 \ No newline at end of file +max-complexity = 12 +ignore = E203, W503 diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index bcbccfb..d80e741 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -63,14 +63,10 @@ jobs: if: steps.cache-deps.outputs.cache-hit != 'true' - name: Check code formatting with black - run: poetry run black --check . + run: poetry run black . --check - name: Lint with flake8 - run: | - # stop the build if there are Python syntax errors or undefined names - poetry run flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics - # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide - poetry run flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics + run: poetry run flake8 . --count --show-source - name: Test with pytest run: poetry run pytest From ab99826a309dadd5bb3679dc7f44ea754b72b0c1 Mon Sep 17 00:00:00 2001 From: Bernd Doser Date: Tue, 10 Sep 2024 11:08:21 +0200 Subject: [PATCH 3/7] fix flake8 linter issues --- docs/contributing.md | 13 +++++-------- tests/test_dynamo_export.py | 2 -- tests/test_onnx_export.py | 2 -- 3 files changed, 5 insertions(+), 12 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 0fadaaa..c0593e3 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -6,11 +6,9 @@ We welcome contributions to the Spherinator & HiPSter project. This document out The project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Please read the code of conduct before contributing to the project. -## Clear design and best practices +## Use best practices for a clean codebase -The Python must adhere the [PEP8 Python coding style guide](https://peps.python.org/pep-0008/) for formatting and syntax. The [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) provides additional guidelines for writing clean and readable code. - -The Spherinator is using the design principles of the [PyTorch Lightning](https://lightning.ai/docs/pytorch/stable/) library. +The Python must adhere the [PEP8 Python coding style guide](https://peps.python.org/pep-0008/) for formatting and syntax. The [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) provides additional guidelines for writing clean and readable code. The Spherinator is using the design principles of the [PyTorch Lightning](https://lightning.ai/docs/pytorch/stable/) library. ## Python dependencies @@ -19,12 +17,11 @@ The project uses [Poetry](https://python-poetry.org/) for dependency management. ## Documentation Write docstrings for all public modules, functions, classes, and methods. Follow docstring conventions as outlined by [PEP 257](https://peps.python.org/pep-0257/). - The user documentation is located in the `docs` directory and will be generated with [Sphinx](https://www.sphinx-doc.org/en/master/index.html) and hosted on [Read The Docs](https://spherinator.readthedocs.io/en/latest/index.html). ## Testing -The code is tested using [pytest](https://docs.pytest.org). All tests are located in the `tests` directory. +The code is tested using [pytest](https://docs.pytest.org). All tests are located in the `tests` directory. Please write tests for all new code and ensure that all tests pass before creating a pull request. The CI workflow will run the tests and fail if any test fails. ## Continuous Integration @@ -33,12 +30,12 @@ GitHub Actions is used for continuous integration. The CI workflow is defined in ## Code Formatting The Python code must be formatted with [black](https://black.readthedocs.io/en/stable/). -This can be done manually by running `black .` in the project directory or by installing the vscode extension `ms-python.black-formatter` and enabling the format on save option. +This can be done manually by running `black .` in the project directory or by installing the vscode extension `ms-python.black-formatter`. The format on save option is enabled for `vscode` in the `.vscode/settings.json` file. The CI workflow will check the code formatting and fail if the code is not formatted correctly. ## Static code analysis -The code is analyzed using [flake8](https://flake8.pycqa.org/en/latest/). +The code is analyzed using [flake8](https://flake8.pycqa.org/en/latest/). The CI workflow will check the code for any issues reported by flake8 and fail if any issues are found. ## Pull requests diff --git a/tests/test_dynamo_export.py b/tests/test_dynamo_export.py index b115719..5ff78b7 100644 --- a/tests/test_dynamo_export.py +++ b/tests/test_dynamo_export.py @@ -1,5 +1,3 @@ -import sys - import pytest import torch import torch.nn as nn diff --git a/tests/test_onnx_export.py b/tests/test_onnx_export.py index f4f5e4f..7dc7168 100644 --- a/tests/test_onnx_export.py +++ b/tests/test_onnx_export.py @@ -1,5 +1,3 @@ -import sys - import pytest import torch import torch.nn as nn From 75e789d654d87f963a7064f4a0bfa23e9bd14696 Mon Sep 17 00:00:00 2001 From: Bernd Doser Date: Tue, 10 Sep 2024 11:08:43 +0200 Subject: [PATCH 4/7] fix flake8 linter issue --- docs/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 11c328e..579a1ea 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,7 +4,10 @@ project = "Spherinator" copyright = f"{datetime.now().year}, HITS gGmbH" -author = "Kai Polsterer , Bernd Doser , Andreas Fehlner , Sebastian T. Gomez " +author = """Kai Polsterer , + Bernd Doser , + Andreas Fehlner , + Sebastian T. Gomez """ extensions = [ "myst_parser", From 73b4d22ee4ad0f1ebe2e622c08d431278298a048 Mon Sep 17 00:00:00 2001 From: Bernd Doser Date: Tue, 10 Sep 2024 12:07:41 +0200 Subject: [PATCH 5/7] clarify contributing --- docs/contributing.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index c0593e3..d021ce6 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -8,7 +8,7 @@ The project follows the [Contributor Covenant Code of Conduct](https://www.contr ## Use best practices for a clean codebase -The Python must adhere the [PEP8 Python coding style guide](https://peps.python.org/pep-0008/) for formatting and syntax. The [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) provides additional guidelines for writing clean and readable code. The Spherinator is using the design principles of the [PyTorch Lightning](https://lightning.ai/docs/pytorch/stable/) library. +The Python code must adhere to the [PEP8 Python coding style guide](https://peps.python.org/pep-0008/) for formatting and syntax. The [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) provides additional guidelines for writing clean and readable code. The Spherinator is using the design principles of the [PyTorch Lightning](https://lightning.ai/docs/pytorch/stable/) library. ## Python dependencies @@ -21,7 +21,7 @@ The user documentation is located in the `docs` directory and will be generated ## Testing -The code is tested using [pytest](https://docs.pytest.org). All tests are located in the `tests` directory. Please write tests for all new code and ensure that all tests pass before creating a pull request. The CI workflow will run the tests and fail if any test fails. +The code is tested using [pytest](https://docs.pytest.org). All tests are located in the `tests` directory. Please write tests for all new code and ensure all tests pass before creating a pull request. The CI workflow will run the tests and fail if any test fails. ## Continuous Integration @@ -35,20 +35,22 @@ The CI workflow will check the code formatting and fail if the code is not forma ## Static code analysis -The code is analyzed using [flake8](https://flake8.pycqa.org/en/latest/). The CI workflow will check the code for any issues reported by flake8 and fail if any issues are found. +The code will be analyzed using [flake8](https://flake8.pycqa.org/en/latest/). +The linting rules are defined in the `.flake8` file. The linter can be run manually by running `flake8` in the project directory. +The CI workflow will check the code for any issues reported by flake8 and fail if any issues are found. ## Pull requests The project uses the [GitHub flow](https://guides.github.com/introduction/flow/) to manage pull requests. -1. Create a fork of the repository. Although you can create a branch in the main repository, it is recommended to create a fork for better isolation. -2. Create a branch in your fork. Let the branch name be descriptive of the changes you are making. +1. Create a fork of the repository. Although you can create a branch in the main repository, creating a fork for better isolation is recommended. +2. Create a branch in your fork. Let the branch name describe the changes you are making. 3. Make the changes in the branch. -4. Create a pull request from your branch to the main repository. -5. Check if all the checks are passing. If not, fix the issues and push the changes to the branch. +4. Check if all the checks are passing. If not, fix the issues and push the changes to the branch. +5. Create a pull request from your branch to the `main` repository and describe your changes. 6. The pull request will be reviewed by the maintainers. The review process may involve multiple iterations of changes and reviews. -7. Please keep the branch up to date with the main repository by rebasing it on the main branch if necessary. -8. Once the pull request is approved, it will be merged into the main repository. +7. Please keep the branch up to date with the `main` repository by rebasing it on the main branch if necessary. +8. Once the pull request is approved, it will be merged into the 'main' repository, and the feature branch will be deleted. ## Issues From a8ef76253832ea08f8fa91f53b46c18c0ceead5e Mon Sep 17 00:00:00 2001 From: Bernd Doser Date: Tue, 10 Sep 2024 13:36:05 +0200 Subject: [PATCH 6/7] fix link to contributing --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 852774b..4ff0e99 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,5 +15,5 @@ The documentation is under construction and not yet complete. For more informati installation.md training.md hipster.md -contribution.md +contributing.md ``` From 82f09c0ee6ebca6c91179b02070fabc049af49be Mon Sep 17 00:00:00 2001 From: Bernd Doser Date: Tue, 10 Sep 2024 15:52:04 +0200 Subject: [PATCH 7/7] fix code primes --- docs/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index d021ce6..4f461aa 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -50,7 +50,7 @@ The project uses the [GitHub flow](https://guides.github.com/introduction/flow/) 5. Create a pull request from your branch to the `main` repository and describe your changes. 6. The pull request will be reviewed by the maintainers. The review process may involve multiple iterations of changes and reviews. 7. Please keep the branch up to date with the `main` repository by rebasing it on the main branch if necessary. -8. Once the pull request is approved, it will be merged into the 'main' repository, and the feature branch will be deleted. +8. Once the pull request is approved, it will be merged into the `main` repository, and the feature branch will be deleted. ## Issues