From 3284a3929c9c4a6171ff6a7b1a78fc60f6ee4bf6 Mon Sep 17 00:00:00 2001 From: Grant Ramsay Date: Sun, 24 Sep 2023 16:28:15 +0100 Subject: [PATCH 1/4] add contributing guidelines will need more fleshing out but a start Signed-off-by: Grant Ramsay --- CONTRIBUTING.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 29 ++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c5040461 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,118 @@ +# Contributing to Py-Maker + +Thank you for your interest in contributing to Py-Maker! We welcome all +contributions, big or small. + +If you are not sure where to start, please take a look at the [open +issues](https://github.com/seapagan/py-maker/issues). If you have an idea for a +new feature or would like to report a bug, please open a new issue. + +We also welcome contributions to the documentation. If you find any errors or +would like to suggest improvements, please open a new issue or submit a pull + +- [Prerequisites](#prerequisites) +- [Getting Started](#getting-started) +- [Install Dependencies](#install-dependencies) +- [Install Git Pre-Commit hooks](#install-git-pre-commit-hooks) +- [Run pre-commit manually](#run-pre-commit-manually) +- [Guidelines](#guidelines) +- [Contact](#contact) + +## Prerequisites + +- Since this is a [Python](https://www.python.org/) project, you will need to have +Python installed on your machine. You can download the latest version of Python +from the [official website](https://www.python.org/downloads/) or using your +Operating system's package manager. + +- I'd recommend using [pyenv](https://github.com/pyenv/pyenv) to manage your +Python installations, the +[pyenv-installer](https://github.com/pyenv/pyenv-installer) works for Linux and +Mac OS X. For Windows, you can use the +[pyenv-win](https://github.com/pyenv-win/pyenv-win) port. See +[here](https://github.com/pyenv-win/pyenv-win#installation ) for installation +instructions. + +- This project requires **Python 3.9** or higher. + +- We also use [Poetry](https://python-poetry.org/) to manage our dependencies. You +should have this installed as well. You can install Poetry by following the +instructions on the [Poetry +website](https://python-poetry.org/docs/#installation). + +## Getting Started + +Before you start contributing, please make sure you have read and understood our +[Code of +Conduct](https://github.com/seapagan/py-maker/blob/main/CODE_OF_CONDUCT.md) and +[License](https://github.com/seapagan/py-maker/blob/main/LICENSE.txt). + +To get started, follow these steps: + +1. Fork the repository and clone it to your local machine. +2. Install the required dependencies (see [next section](#install-dependencies)). +3. Create a new branch for your changes: `git checkout -b my-new-feature`. +4. Make your changes and commit them: `git commit -am 'Add some feature'`. +5. Push your changes to your fork: `git push origin my-new-feature`. +6. Create a new pull request. + +## Install Dependencies + +Run the following command to install the required dependencies: + +```console +$ poetry install +``` + +You then need to activate the virtual environment: + +```console +$ poetry shell +``` + +From here you can start working on the project. If you are using an IDE such as +VSCode or PyCharm, you can set the Python interpreter to the one in the virtual +environment. + +## Install Git Pre-Commit hooks + +Please do this if you are intending to submit a PR. It will check commits +locally before they are pushed up to the Repo. + +```console +$ pre-commit install +pre-commit installed at .git/hooks/pre-commit +``` + +This will ensure that all code meets the required linting standard before being +committed. + +## Run pre-commit manually + +You can run these checks manually on all staged files using the below command : + +```console +poe pre +``` + +## Guidelines + +Here are some guidelines to follow when contributing to [project name]: + +- Follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide. The + pre-commit hooks will check for this. +- Write clear and concise commit messages. +- Write tests for your code. +- Make sure your code passes all tests before submitting a pull request. +- Document your code using + [docstrings](https://www.python.org/dev/peps/pep-0257/). +- Use [GitHub issues](https://github.com/seapagan/py-maker/issues) to report + bugs or suggest new features. + +## Contact + +If you have any questions or need help with contributing, please contact me +. You can also use the [GitHub +Discussions](https://github.com/seapagan/py-maker/discussions) feature. + +Happy contributing! diff --git a/README.md b/README.md index cb269ade..56e99ace 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ Full documentation for this project with usage examples is available at - [Task Runner](#task-runner) - [Pre-commit](#pre-commit) - [GitHub Actions and Configuration](#github-actions-and-configuration) +- [Contributing to Py-Maker](#contributing-to-py-maker) - [License](#license) ## Installation @@ -162,6 +163,34 @@ There are also standard templates for Pull Request and Issues. The plan is to add more workflows in the future, for example running tests and more. +## Contributing to Py-Maker + +All contributions, bug reports, bug fixes, documentation improvements, +enhancements, and ideas are welcome. + +A detailed overview on how to contribute can be found in the **[contributing +guide](CONTRIBUTING.md)** and on the +[website](http://py-maker.seapagan.net/contributing/). + +If you are simply looking to start working with the codebase, navigate to the +[GitHub "issues" tab](https://github.com/seapagan/py-maker/issues) and start +looking through interesting issues. There may be issues listed under +[documentation](https://github.com/seapagan/py-maker/issues?labels=documentation&sort=updated&state=open) +and [good first +issue](https://github.com/seapagan/py-maker/issues?labels=good+first+issue&sort=updated&state=open) +where you could start out. + +You can also triage issues which may include reproducing bug reports, or asking +for vital information such as version numbers or reproduction instructions. + +Maybe through using Py-Maker you have an idea of your own or are looking for +something in the documentation and thinking ‘this can be improved’...you can do +something about it! + +As contributors and maintainers to this project, you are expected to abide by +our code of conduct. More information can be found at: [Contributor Code of +Conduct](https://github.com/seapagan/py-maker/blob/main/CODE_OF_CONDUCT.md) + ## License This project is licensed under the terms of the MIT license. From f9bab7d17780b33293838000a0526390596ab5e0 Mon Sep 17 00:00:00 2001 From: Grant Ramsay Date: Sun, 24 Sep 2023 16:28:30 +0100 Subject: [PATCH 2/4] add contributing info to the Website Signed-off-by: Grant Ramsay --- docs/contributing.md | 2 ++ mkdocs.yml | 1 + pyproject.toml | 4 ++-- 3 files changed, 5 insertions(+), 2 deletions(-) create mode 100644 docs/contributing.md diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..5aff1e3c --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,2 @@ + +--8<-- "CONTRIBUTING.md" diff --git a/mkdocs.yml b/mkdocs.yml index 6e88aa89..cf5af48d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -61,5 +61,6 @@ nav: - Replacing: template/replace.md - Task Runner: tasks.md - Future Plans: future-plans.md + - Contributing: contributing.md - Changelog: changelog.md - License: license.md diff --git a/pyproject.toml b/pyproject.toml index 00783161..09189c74 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -114,8 +114,8 @@ lint = ["black", "flake8", "mypy", "try", "pylint"] "docs:publish" = "mkdocs gh-deploy" "docs:build" = "mkdocs build" -"docs:serve" = "mkdocs serve -w TODO.md -w CHANGELOG.md" -"docs:serve:all" = "mkdocs serve -w TODO.md -w CHANGELOG.md -a 0.0.0.0:9000" +"docs:serve" = "mkdocs serve -w TODO.md -w CHANGELOG.md -w CONTRIBUTING.md" +"docs:serve:all" = "mkdocs serve -w TODO.md -w CHANGELOG.md -w CONTRIBUTING.md -a 0.0.0.0:9000" # configure assorted tools and linters [tool.isort] From a35e9ee872c07d2dd94a61bfd2f73f06be02e6d3 Mon Sep 17 00:00:00 2001 From: Grant Ramsay Date: Sun, 24 Sep 2023 16:41:27 +0100 Subject: [PATCH 3/4] flesh out the CONTRIBUTING a bit Signed-off-by: Grant Ramsay --- .vscode/settings.json | 4 ++-- CONTRIBUTING.md | 30 ++++++++++++++++++++++++++++-- 2 files changed, 30 insertions(+), 4 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 511c386c..906fa74a 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,8 +1,8 @@ { "[python]": { "editor.codeActionsOnSave": { - "source.fixAll": true, - "source.organizeImports": true + "source.fixAll": "always", + "source.organizeImports": "always" }, "editor.defaultFormatter": "ms-python.black-formatter" }, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c5040461..10ec8004 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,6 +15,7 @@ would like to suggest improvements, please open a new issue or submit a pull - [Install Dependencies](#install-dependencies) - [Install Git Pre-Commit hooks](#install-git-pre-commit-hooks) - [Run pre-commit manually](#run-pre-commit-manually) +- [Testing](#testing) - [Guidelines](#guidelines) - [Contact](#contact) @@ -95,12 +96,32 @@ You can run these checks manually on all staged files using the below command : poe pre ``` +## Testing + +We are using [pytest](https://docs.pytest.org/) for testing. + +At the moment the test framework is set up but we only have minimal tests. We +will be adding more tests as we go along - and most definitely welcome any +contributions to this area! + +If you add any new features, please add tests for them. This will help us to +ensure that the code is working as expected and will prevent any regressions. +*Currently we are not enforcing this until we have better coverage of the code.* + ## Guidelines Here are some guidelines to follow when contributing to [project name]: - Follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide. The - pre-commit hooks will check for this. + pre-commit hooks will check for this. [Black](https://black.readthedocs.io/) + is installed and this is the format we are using. +- Try to have no linting errors or warnings. The pre-commit hooks will check for + this also. [Flake8](https://flake8.pycqa.org/en/latest/) is installed and + there are a few other linters that are run as well. +- [MyPy](https://mypy.readthedocs.io/en/stable/) is installed and we are using + type hints. Please try to add type hints to your code. If you see any areas of + the code that are missing type hints, please feel free to open a PR and add + them 😁! - Write clear and concise commit messages. - Write tests for your code. - Make sure your code passes all tests before submitting a pull request. @@ -109,10 +130,15 @@ Here are some guidelines to follow when contributing to [project name]: - Use [GitHub issues](https://github.com/seapagan/py-maker/issues) to report bugs or suggest new features. +If you are using VSCode, there is a config file in the `.vscode` folder that +will help you to follow these guidelines. You may need to install some +extensions to get the most out of it. I'll add a list of recommended extensions +here soon. The `Python` one is a must though. + ## Contact If you have any questions or need help with contributing, please contact me -. You can also use the [GitHub +**@seapagan** on GitHub. You can also use the [GitHub Discussions](https://github.com/seapagan/py-maker/discussions) feature. Happy contributing! From 2d9ffa24df34954d24e25ede368ddc1ef58adc16 Mon Sep 17 00:00:00 2001 From: Grant Ramsay Date: Sun, 24 Sep 2023 17:22:52 +0100 Subject: [PATCH 4/4] fill in mising placeholder Signed-off-by: Grant Ramsay --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 10ec8004..d4f1fb19 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -110,7 +110,7 @@ ensure that the code is working as expected and will prevent any regressions. ## Guidelines -Here are some guidelines to follow when contributing to [project name]: +Here are some guidelines to follow when contributing to Py-Maker: - Follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide. The pre-commit hooks will check for this. [Black](https://black.readthedocs.io/)