diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index ebb44c2..f76d725 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,32 +1,28 @@ // For format details, see https://aka.ms/devcontainer.json. For config options, see the // README at: https://github.com/devcontainers/templates/tree/main/src/python { - "name": "Cookiecutter Poetry", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye", - "features": { - "ghcr.io/devcontainers-contrib/features/cookiecutter:2": {}, - "ghcr.io/devcontainers-contrib/features/poetry:2": {} - }, + "name": "Cookiecutter Poetry", + // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile + "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye", + "features": { + "ghcr.io/devcontainers-contrib/features/cookiecutter:2": {}, + "ghcr.io/devcontainers-contrib/features/poetry:2": {} + }, - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "./.devcontainer/postCreateCommand.sh", + // Use 'postCreateCommand' to run commands after the container is created. + "postCreateCommand": "./.devcontainer/postCreateCommand.sh", - // Configure tool-specific properties. - "customizations": { - "vscode": { - "extensions": [ - "ms-python.python" - ], - "settings": { - "python.testing.pytestArgs": [ - "tests" - ], - "python.testing.unittestEnabled": false, - "python.testing.pytestEnabled": true, - "python.defaultInterpreterPath": "/workspaces/cookiecutter-poetry/.venv/bin/python", - "python.testing.pytestPath": "/workspaces/cookiecutter-poetry/.venv/bin/pytest" - } - } - } + // Configure tool-specific properties. + "customizations": { + "vscode": { + "extensions": ["ms-python.python", "editorconfig.editorconfig"], + "settings": { + "python.testing.pytestArgs": ["tests"], + "python.testing.unittestEnabled": false, + "python.testing.pytestEnabled": true, + "python.defaultInterpreterPath": "/workspaces/cookiecutter-poetry/.venv/bin/python", + "python.testing.pytestPath": "/workspaces/cookiecutter-poetry/.venv/bin/pytest" + } + } + } } diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..64b7dff --- /dev/null +++ b/.editorconfig @@ -0,0 +1,6 @@ +[*] +max_line_length = 120 + +[*.json] +indent_style = space +indent_size = 4 diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index cbc66a7..972c072 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -24,9 +24,9 @@ Steps to reproduce the behavior: **System [please complete the following information]:** -- OS: e.g. [Ubuntu 18.04] -- Language Version: [e.g. Python 3.8] -- Virtual environment: [e.g. Poetry 1.1.13] +- OS: e.g. [Ubuntu 18.04] +- Language Version: [e.g. Python 3.8] +- Virtual environment: [e.g. Poetry 1.1.13] **Additional context** diff --git a/.github/actions/setup-poetry-env/action.yml b/.github/actions/setup-poetry-env/action.yml index a7cdeb8..22e4053 100644 --- a/.github/actions/setup-poetry-env/action.yml +++ b/.github/actions/setup-poetry-env/action.yml @@ -2,10 +2,10 @@ name: "setup-poetry-env" description: "Composite action to setup the Python and poetry environment." inputs: - python-version: - required: false - description: "The python version to use" - default: "3.11" + python-version: + required: false + description: "The python version to use" + default: "3.11" runs: using: "composite" diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 53aa5dc..df1aaf8 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,9 +1,9 @@ **PR Checklist** -- [ ] A description of the changes is added to the description of this PR. -- [ ] If there is a related issue, make sure it is linked to this PR. -- [ ] If you've fixed a bug or added code that should be tested, add tests! -- [ ] Documentation in `docs` is updated +- [ ] A description of the changes is added to the description of this PR. +- [ ] If there is a related issue, make sure it is linked to this PR. +- [ ] If you've fixed a bug or added code that should be tested, add tests! +- [ ] Documentation in `docs` is updated **Description of changes** diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 16ac87b..3149526 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -35,7 +35,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python-version: ['3.8', '3.9', '3.10', '3.11'] + python-version: ["3.8", "3.9", "3.10", "3.11"] fail-fast: false steps: - name: Check out diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ac5ec31..fa16b7e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -12,3 +12,9 @@ repos: hooks: - id: black exclude: ^{{cookiecutter.project_name}} + + - repo: https://github.com/pre-commit/mirrors-prettier + rev: "v3.0.3" + hooks: + - id: prettier + exclude: ^{{cookiecutter.project_name}} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d042c3b..8850949 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing -Contributions are welcome, and they are greatly appreciated! Every -little bit helps, and credit will always be given. +Contributions are welcome, and they are greatly appreciated! +Every little bit helps, and credit will always be given. You can contribute in many ways: @@ -13,128 +13,114 @@ Report bugs at

@@ -12,13 +10,17 @@ [![Docs](https://img.shields.io/badge/docs-gh--pages-blue)](https://fpgmaas.github.io/cookiecutter-poetry/) [![License](https://img.shields.io/github/license/fpgmaas/cookiecutter-poetry)](https://img.shields.io/github/license/fpgmaas/cookiecutter-poetry) - This is a modern Cookiecutter template that can be used to initiate a Python project with all the necessary tools for development, testing, and deployment. It supports the following features: - [Poetry](https://python-poetry.org/) for dependency management - CI/CD with [GitHub Actions](https://github.com/features/actions) - Pre-commit hooks with [pre-commit](https://pre-commit.com/) -- Code quality with [black](https://pypi.org/project/black/), [ruff](https://github.com/charliermarsh/ruff), [mypy](https://mypy.readthedocs.io/en/stable/), and [deptry](https://github.com/fpgmaas/deptry/) +- Code quality with: + - [black](https://pypi.org/project/black/) + - [ruff](https://github.com/charliermarsh/ruff) + - [mypy](https://mypy.readthedocs.io/en/stable/) + - [deptry](https://github.com/fpgmaas/deptry/) + - [prettier](https://prettier.io/) - Publishing to [Pypi](https://pypi.org) or [Artifactory](https://jfrog.com/artifactory) by creating a new release on GitHub - Testing and coverage with [pytest](https://docs.pytest.org/en/7.1.x/) and [codecov](https://about.codecov.io/) - Documentation with [MkDocs](https://www.mkdocs.org/) @@ -26,6 +28,7 @@ This is a modern Cookiecutter template that can be used to initiate a Python pro - Containerization with [Docker](https://www.docker.com/) --- +

Documentation - Example - PyPi @@ -33,15 +36,12 @@ This is a modern Cookiecutter template that can be used to initiate a Python pro --- - - - ## Quickstart On your local machine, navigate to the directory in which you want to create a project directory, and run the following two commands: -``` bash +```bash pip install cookiecutter-poetry ccp ``` @@ -49,7 +49,7 @@ ccp Alternatively, install `cookiecutter` and directly pass the URL to this Github repository to the `cookiecutter` command: -``` bash +```bash pip install cookiecutter cookiecutter https://github.com/fpgmaas/cookiecutter-poetry.git ``` @@ -57,7 +57,7 @@ cookiecutter https://github.com/fpgmaas/cookiecutter-poetry.git Create a repository on GitHub, and then run the following commands, replacing ``, with the name that you gave the Github repository and `` with your Github username. -``` bash +```bash cd git init -b main git add . @@ -68,9 +68,9 @@ git push -u origin main Finally, install the environment and the pre-commit hooks with - ```bash - make install - ``` +```bash +make install +``` You are now ready to start development on your project! The CI/CD pipeline will be triggered when you open a pull request, merge to main, diff --git a/cookiecutter.json b/cookiecutter.json index dccfeb8..e5f2b21 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -1,16 +1,23 @@ { "author": "Florian Maas", "email": "fpgmaas@gmail.com", - "author_github_handle" : "fpgmaas", + "author_github_handle": "fpgmaas", "project_name": "example-project", "project_slug": "{{cookiecutter.project_name|lower|replace('-', '_')}}", "project_description": "This is a template repository for Python projects that use Poetry for their dependency management.", - "include_github_actions": ["y","n"], + "include_github_actions": ["y", "n"], "publish_to": ["pypi", "artifactory", "none"], "deptry": ["y", "n"], "mkdocs": ["y", "n"], - "codecov" : ["y","n"], - "dockerfile" : ["y","n"], - "devcontainer" : ["y","n"], - "open_source_license": ["MIT license", "BSD license", "ISC license", "Apache Software License 2.0", "GNU General Public License v3", "Not open source"] + "codecov": ["y", "n"], + "dockerfile": ["y", "n"], + "devcontainer": ["y", "n"], + "open_source_license": [ + "MIT license", + "BSD license", + "ISC license", + "Apache Software License 2.0", + "GNU General Public License v3", + "Not open source" + ] } diff --git a/docs/features/cicd.md b/docs/features/cicd.md index 177dd6c..9b3ee2c 100644 --- a/docs/features/cicd.md +++ b/docs/features/cicd.md @@ -1,4 +1,3 @@ - # CI/CD with Github actions when `include_github_actions` is set to `"y"`, a `.github` directory is @@ -35,7 +34,7 @@ versions if `tox` is set to `"y"`. # How to trigger a release? -To trigger a new release, navigate to your repository on GitHub, click ``Releases`` on the right, and then select `Draft +To trigger a new release, navigate to your repository on GitHub, click `Releases` on the right, and then select `Draft a new release`. If you fail to find the button, you could also directly visit `https://github.com///releases/new`. diff --git a/docs/features/codecov.md b/docs/features/codecov.md index 443b946..19de8e4 100644 --- a/docs/features/codecov.md +++ b/docs/features/codecov.md @@ -5,7 +5,7 @@ and `make test` will run the tests and output a coverage report as `coverage.xml If `include_github_actions` is set to `"y"`, coverage tests with [codecov](https://about.codecov.io/) are added to the CI/CD pipeline. To enable this, sign up at [codecov.io](https://about.codecov.io/) with your GitHub account. Additionally, a `codecov.yaml` file is created, with the following defaults: -``` yaml +```yaml # Badge color changes from red to green between 70% and 100% # PR pipeline fails if codecov falls with 1% diff --git a/docs/features/linting.md b/docs/features/linting.md index 6adbf63..2135402 100644 --- a/docs/features/linting.md +++ b/docs/features/linting.md @@ -2,7 +2,7 @@ Code can be linted and quality-checked with the command -``` bash +```bash make check ``` @@ -119,6 +119,20 @@ exclude = [ ] ``` +# Prettier + +[Prettier](https://prettier.io/) is used to format the markdown documentation, along with any json and yaml files. +Its options can be configured in the included `.editorconfig` file or in greater detail by adding a `.prettierrc` file ([See Docs](https://prettier.io/docs/en/configuration)). + +```yaml +[*] +max_line_length = 120 + +[*.json] +indent_style = space +indent_size = 4 +``` + ## Github Actions If `include_github_actions` is set to `"y"`, code formatting is checked diff --git a/docs/features/mkdocs.md b/docs/features/mkdocs.md index 27e836e..a34b5f8 100644 --- a/docs/features/mkdocs.md +++ b/docs/features/mkdocs.md @@ -1,6 +1,5 @@ # Documentation with MkDocs - If `mkdocs` is set to `"y"`, documentation of your project is automatically added using [MkDocs](https://www.mkdocs.org/). Next to that, if @@ -10,7 +9,7 @@ automatically deployed to your `gh-pages` branch, and made available at To view the documentation locally, simply run -``` bash +```bash make docs ``` @@ -21,10 +20,10 @@ This command will generate and build your documentation, and start the server lo To enable your documentation on GitHub, first create a [new release](./cicd.md#how-to-trigger-a-release). -Then, in your repository, navigate to ``Settings > Code and Automation > Pages``. If you succesfully created a new release, -you should see a notification saying `` Your site is ready to be published at https://.github.io//``. +Then, in your repository, navigate to `Settings > Code and Automation > Pages`. If you succesfully created a new release, +you should see a notification saying ` Your site is ready to be published at https://.github.io//`. -To finalize deploying your documentation, under ``Source``, select the branch ``gh-pages``. Your documentation should then be live within a few minutes. +To finalize deploying your documentation, under `Source`, select the branch `gh-pages`. Your documentation should then be live within a few minutes. ## Documenting docstrings @@ -36,7 +35,7 @@ docstrings. An example of a Google style docstring: -``` python +```python def function_with_pep484_type_annotations(param1: int, param2: str) -> bool: """Example function with PEP 484 type annotations. diff --git a/docs/features/poetry.md b/docs/features/poetry.md index 0440ccd..ddb4438 100644 --- a/docs/features/poetry.md +++ b/docs/features/poetry.md @@ -1,19 +1,18 @@ # Dependency management with Poetry - The generated repository will uses [Poetry](https://python-Poetry.org/) for its dependency management. When you have created your repository using this cookiecutter template, a Poetry environment is pre-configured in `pyproject.toml` and `Poetry.toml`. All you need to do is add your project-specific dependencies with -``` bash +```bash poetry add ``` and then install the environment with -``` bash +```bash make install ``` diff --git a/docs/features/publishing.md b/docs/features/publishing.md index 06b5c2a..b00f026 100644 --- a/docs/features/publishing.md +++ b/docs/features/publishing.md @@ -39,6 +39,6 @@ It is also possible to release locally, although it is not recommended. To do so, set the repository secrets listed in the sections above as environment variables on your local machine instead, and run -``` bash +```bash make build-and-publish ``` diff --git a/docs/features/pytest.md b/docs/features/pytest.md index da3e264..ecc5483 100644 --- a/docs/features/pytest.md +++ b/docs/features/pytest.md @@ -4,7 +4,7 @@ the environment. There will be a template unittest in the `tests` directory upon creation of the project, which can be run with -``` bash +```bash make test ``` diff --git a/docs/index.md b/docs/index.md index d528b24..f5ca395 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,3 @@ - -

@@ -37,7 +35,7 @@ An example of a repository generated with this package can be found [here](https On your local machine, navigate to the directory in which you want to create a project directory, and run the following two commands: -``` bash +```bash pip install cookiecutter-poetry ccp ``` @@ -45,7 +43,7 @@ ccp Alternatively, install `cookiecutter` and directly pass the URL to this Github repository to the `cookiecutter` command: -``` bash +```bash pip install cookiecutter cookiecutter https://github.com/fpgmaas/cookiecutter-poetry.git ``` @@ -53,7 +51,7 @@ cookiecutter https://github.com/fpgmaas/cookiecutter-poetry.git Create a repository on GitHub, and then run the following commands, replacing ``, with the name that you gave the Github repository and `` with your Github username. -``` bash +```bash cd git init -b main git add . diff --git a/docs/prompt_arguments.md b/docs/prompt_arguments.md index 949e006..d9dbbba 100644 --- a/docs/prompt_arguments.md +++ b/docs/prompt_arguments.md @@ -1,13 +1,13 @@ # Prompt arguments -When running the command ``ccp`` a prompt will start which enables you to configure your repository. The +When running the command `ccp` a prompt will start which enables you to configure your repository. The prompt values and their explanation are as follows: --- **author** - Your full name. +Your full name. **email** @@ -27,7 +27,7 @@ and it should only contain alphanumeric characters and `-`'s. The project slug, will default to the `project_name` with all `-`'s replaced with `_`. This will be how you import your code later, e.g. -``` python +```python from import foo ``` @@ -76,6 +76,6 @@ will be deployed to the `gh-pages` branch. **open_source_license** Choose a [license](https://choosealicense.com/). Options: - `["1. MIT License", "2. BSD license", "3. ISC license", "4. Apache Software License 2.0", "5. GNU General Public License v3", "6. Not open source"]` +`["1. MIT License", "2. BSD license", "3. ISC license", "4. Apache Software License 2.0", "5. GNU General Public License v3", "6. Not open source"]` --- diff --git a/docs/tutorial.md b/docs/tutorial.md index c26397e..a210ff7 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -7,7 +7,7 @@ This page contains a complete tutorial on how to create your project. To start, we will need to install `poetry`. The instructions to install poetry can be found [here](https://python-poetry.org/docs/). After installing, it is recommended to run -``` bash +```bash poetry config virtualenvs.in-project true ``` @@ -25,13 +25,13 @@ poetry can be found [here](https://python-poetry.org/docs/). Install a version of Python with pyenv. To see a list of available versions, run: -``` bash +```bash pyenv install --list ``` Select a version and install it with -``` bash +```bash pyenv install -v 3.9.7 ``` @@ -43,13 +43,13 @@ First, navigate to the directory in which you want the project to be created. Then, we need to install `cookiecutter-poetry` with the following command: -``` bash +```bash pip install cookiecutter-poetry ``` Within the directory in which you want to create your project, run: -``` bash +```bash ccp ``` @@ -60,7 +60,7 @@ An alternative to the steps above would be to install `cookiecutter` and directly pass the URL to Github repository to the `cookiecutter` command: -``` bash +```bash pip install cookiecutter-poetry cookiecutter https://github.com/fpgmaas/cookiecutter-poetry.git ``` @@ -78,7 +78,7 @@ Run the following commands, replacing `` with the name that you also gave the Github repository and `` with your Github username. -``` bash +```bash cd git init -b main git add . @@ -97,7 +97,7 @@ pyenv local x.y.z Install and activate the `poetry` environment by running: -``` bash +```bash make install poetry shell ``` @@ -115,7 +115,7 @@ instructions on how to do that, see [here](./features/publishing.md#set-up-for-p ## Step 9: Create a new release -To trigger a new release, navigate to your repository on GitHub, click ``Releases`` on the right, and then select `Draft +To trigger a new release, navigate to your repository on GitHub, click `Releases` on the right, and then select `Draft a new release`. If you fail to find the button, you could also directly visit `https://github.com///releases/new`. @@ -124,10 +124,10 @@ Give your release a title, and add a new tag in the form `*.*.*` where the ## Step 10: Enable your documentation -In your repository, navigate to ``Settings > Code and Automation > Pages``. If you succesfully created a new release, -you should see a notification saying `` Your site is ready to be published at https://.github.io//``. +In your repository, navigate to `Settings > Code and Automation > Pages`. If you succesfully created a new release, +you should see a notification saying ` Your site is ready to be published at https://.github.io//`. -To finalize deploying your documentation, under ``Source``, select the branch ``gh-pages``. +To finalize deploying your documentation, under `Source`, select the branch `gh-pages`. ## Step 11: You're all set! diff --git a/mkdocs.yml b/mkdocs.yml index 08fc672..1b4f8e1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,17 +10,17 @@ copyright: Maintained by Florian. nav: - Home: index.md - Features: - - CI/CD with Github Actions: features/cicd.md - - Linting & code quality: features/linting.md - - Makefile: features/makefile.md - - Dependency management with Poetry: features/poetry.md - - Publishing to PyPi or Artifactory: features/publishing.md - - Testing with Pytest: features/pytest.md - - Test coverage with codecov: features/codecov.md - - Documentation with MkDocs: features/mkdocs.md - - Compatibility testing with Tox: features/tox.md - - Containerization with Docker: features/docker.md - - Devcontainer with VSCode: features/devcontainer.md + - CI/CD with Github Actions: features/cicd.md + - Linting & code quality: features/linting.md + - Makefile: features/makefile.md + - Dependency management with Poetry: features/poetry.md + - Publishing to PyPi or Artifactory: features/publishing.md + - Testing with Pytest: features/pytest.md + - Test coverage with codecov: features/codecov.md + - Documentation with MkDocs: features/mkdocs.md + - Compatibility testing with Tox: features/tox.md + - Containerization with Docker: features/docker.md + - Devcontainer with VSCode: features/devcontainer.md - Tutorial: tutorial.md - Prompt Arguments: prompt_arguments.md plugins: diff --git a/{{cookiecutter.project_name}}/.devcontainer/devcontainer.json b/{{cookiecutter.project_name}}/.devcontainer/devcontainer.json index c016aa9..c83a2b3 100644 --- a/{{cookiecutter.project_name}}/.devcontainer/devcontainer.json +++ b/{{cookiecutter.project_name}}/.devcontainer/devcontainer.json @@ -1,31 +1,30 @@ // For format details, see https://aka.ms/devcontainer.json. For config options, see the // README at: https://github.com/devcontainers/templates/tree/main/src/python { - "name": "{{cookiecutter.project_name}}", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye", - "features": { - "ghcr.io/devcontainers-contrib/features/poetry:2": {} - }, + "name": "{{cookiecutter.project_name}}", + // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile + "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye", + "features": { + "ghcr.io/devcontainers-contrib/features/poetry:2": {} + }, - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "./.devcontainer/postCreateCommand.sh", + // Use 'postCreateCommand' to run commands after the container is created. + "postCreateCommand": "./.devcontainer/postCreateCommand.sh", - // Configure tool-specific properties. - "customizations": { - "vscode": { - "extensions": [ - "ms-python.python" - ], - "settings": { - "python.testing.pytestArgs": [ - "tests" - ], - "python.testing.unittestEnabled": false, - "python.testing.pytestEnabled": true, - "python.defaultInterpreterPath": "/workspaces/{{cookiecutter.project_name}}/.venv/bin/python", - "python.testing.pytestPath": "/workspaces/{{cookiecutter.project_name}}/.venv/bin/pytest" - } - } - } + // Configure tool-specific properties. + "customizations": { + "vscode": { + "extensions": [ + "ms-python.python", + "editorconfig.editorconfig", + ], + "settings": { + "python.testing.pytestArgs": ["tests"], + "python.testing.unittestEnabled": false, + "python.testing.pytestEnabled": true, + "python.defaultInterpreterPath": "/workspaces/{{cookiecutter.project_name}}/.venv/bin/python", + "python.testing.pytestPath": "/workspaces/{{cookiecutter.project_name}}/.venv/bin/pytest" + } + } + } } diff --git a/{{cookiecutter.project_name}}/.editorconfig b/{{cookiecutter.project_name}}/.editorconfig new file mode 100644 index 0000000..9395b54 --- /dev/null +++ b/{{cookiecutter.project_name}}/.editorconfig @@ -0,0 +1,5 @@ +max_line_length = 120 + +[*.json] +indent_style = space +indent_size = 4 diff --git a/{{cookiecutter.project_name}}/.pre-commit-config.yaml b/{{cookiecutter.project_name}}/.pre-commit-config.yaml index 34edc57..f508f0a 100644 --- a/{{cookiecutter.project_name}}/.pre-commit-config.yaml +++ b/{{cookiecutter.project_name}}/.pre-commit-config.yaml @@ -18,3 +18,8 @@ repos: rev: "22.8.0" hooks: - id: black + + - repo: https://github.com/pre-commit/mirrors-prettier + rev: "v3.0.3" + hooks: + - id: prettier diff --git a/{{cookiecutter.project_name}}/CONTRIBUTING.md b/{{cookiecutter.project_name}}/CONTRIBUTING.md new file mode 100644 index 0000000..a14a8e1 --- /dev/null +++ b/{{cookiecutter.project_name}}/CONTRIBUTING.md @@ -0,0 +1,133 @@ +# Contributing to `{{cookiecutter.project_name}}` + +Contributions are welcome, and they are greatly appreciated! +Every little bit helps, and credit will always be given. + +You can contribute in many ways: + +# Types of Contributions + +## Report Bugs + +Report bugs at https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/issues + +If you are reporting a bug, please include: + +- Your operating system name and version. +- Any details about your local setup that might be helpful in troubleshooting. +- Detailed steps to reproduce the bug. + +## Fix Bugs + +Look through the GitHub issues for bugs. +Anything tagged with "bug" and "help wanted" is open to whoever wants to implement a fix for it. + +## Implement Features + +Look through the GitHub issues for features. +Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it. + +## Write Documentation + +Cookiecutter PyPackage could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such. + +## Submit Feedback + +The best way to send feedback is to file an issue at https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/issues. + +If you are proposing a new feature: + +- Explain in detail how it would work. +- Keep the scope as narrow as possible, to make it easier to implement. +- Remember that this is a volunteer-driven project, and that contributions + are welcome :) + +# Get Started! + +Ready to contribute? Here's how to set up `{{cookiecutter.project_name}}` for local development. +Please note this documentation assumes you already have `poetry` and `Git` installed and ready to go. + +1. Fork the `{{cookiecutter.project_name}}` repo on GitHub. + +2. Clone your fork locally: + +```bash +cd +git clone git@github.com:YOUR_NAME/{{cookiecutter.project_name}}.git +``` + +3. Now we need to install the environment. Navigate into the directory + +```bash +cd {{cookiecutter.project_name}} +``` + +If you are using `pyenv`, select a version to use locally. (See installed versions with `pyenv versions`) + +```bash +pyenv local +``` + +Then, install and activate the environment with: + +```bash +poetry install +poetry shell +``` + +4. Install pre-commit to run linters/formatters at commit time: + +```bash +poetry run pre-commit install +``` + +5. Create a branch for local development: + +```bash +git checkout -b name-of-your-bugfix-or-feature +``` + +Now you can make your changes locally. + +6. Don't forget to add test cases for your added functionality to the `tests` directory. + +7. When you're done making changes, check that your changes pass the formatting tests. + +```bash +make check +``` + +Now, validate that all unit tests are passing: + +```bash +make test +``` + +9. Before raising a pull request you should also run tox. + This will run the tests across different versions of Python: + +```bash +tox +``` + +This requires you to have multiple versions of python installed. +This step is also triggered in the CI/CD pipeline, so you could also choose to skip this step locally. + +10. Commit your changes and push your branch to GitHub: + +```bash +git add . +git commit -m "Your detailed description of your changes." +git push origin name-of-your-bugfix-or-feature +``` + +11. Submit a pull request through the GitHub website. + +# Pull Request Guidelines + +Before you submit a pull request, check that it meets these guidelines: + +1. The pull request should include tests. + +2. If the pull request adds functionality, the docs should be updated. + Put your new functionality into a function with a docstring, and add the feature to the list in `README.md`. diff --git a/{{cookiecutter.project_name}}/CONTRIBUTING.rst b/{{cookiecutter.project_name}}/CONTRIBUTING.rst deleted file mode 100644 index bd075a8..0000000 --- a/{{cookiecutter.project_name}}/CONTRIBUTING.rst +++ /dev/null @@ -1,151 +0,0 @@ -============ -Contributing -============ - -Contributions are welcome, and they are greatly appreciated! Every little bit -helps, and credit will always be given. - -You can contribute in many ways: - -Types of Contributions ----------------------- - -Report Bugs -~~~~~~~~~~~ - -Report bugs at https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/issues - -If you are reporting a bug, please include: - -* Your operating system name and version. -* Any details about your local setup that might be helpful in troubleshooting. -* Detailed steps to reproduce the bug. - -Fix Bugs -~~~~~~~~ - -Look through the GitHub issues for bugs. Anything tagged with "bug" -and "help wanted" is open to whoever wants to implement a fix for it. - -Implement Features -~~~~~~~~~~~~~~~~~~ - -Look through the GitHub issues for features. Anything tagged with "enhancement" -and "help wanted" is open to whoever wants to implement it. - -Write Documentation -~~~~~~~~~~~~~~~~~~~ - -Cookiecutter PyPackage could always use more documentation, whether as part of -the official docs, in docstrings, or even on the web in blog posts, articles, -and such. - -Submit Feedback -~~~~~~~~~~~~~~~ - -The best way to send feedback is to file an issue at -https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/issues. - -If you are proposing a new feature: - -* Explain in detail how it would work. -* Keep the scope as narrow as possible, to make it easier to implement. -* Remember that this is a volunteer-driven project, and that contributions - are welcome :) - -Get Started! ------------- - -Ready to contribute? Here's how to set up `{{cookiecutter.project_name}}` for local -development. Please note this documentation assumes you already have -`poetry` and `Git` installed and ready to go. - -| 1. Fork the `{{cookiecutter.project_name}}` repo on GitHub. - -| 2. Clone your fork locally: - - .. code-block:: bash - - cd - git clone git@github.com:YOUR_NAME/{{cookiecutter.project_name}}.git - - -| 3. Now we need to install the environment. Navigate into the directory - - .. code-block:: bash - - cd {{cookiecutter.project_name}} - - If you are using ``pyenv``, select a version to use locally. (See installed versions with ``pyenv versions``) - - .. code-block:: bash - - pyenv local - - Then, install and activate the environment with: - - .. code-block:: bash - - poetry install - poetry shell - -| 4. Install pre-commit to run linters/formatters at commit time: - - .. code-block:: bash - - poetry run pre-commit install - -| 5. Create a branch for local development: - - .. code-block:: bash - - git checkout -b name-of-your-bugfix-or-feature - - Now you can make your changes locally. - - -| 6. Don't forget to add test cases for your added functionality to the ``tests`` directory. - -| 7. When you're done making changes, check that your changes pass the formatting tests. - - .. code-block:: bash - - make check - -| 8. Now, validate that all unit tests are passing: - - .. code-block:: bash - - make test - -| 9. Before raising a pull request you should also run tox. This will run the - tests across different versions of Python: - - .. code-block:: bash - - tox - - This requires you to have multiple versions of python installed. - This step is also triggered in the CI/CD pipeline, so you could also choose to skip this - step locally. - -| 10. Commit your changes and push your branch to GitHub: - - .. code-block:: bash - - git add . - git commit -m "Your detailed description of your changes." - git push origin name-of-your-bugfix-or-feature - -| 11. Submit a pull request through the GitHub website. - -Pull Request Guidelines ---------------------------- - -Before you submit a pull request, check that it meets these guidelines: - -1. The pull request should include tests. - -2. If the pull request adds functionality, the docs should be updated. Put your - new functionality into a function with a docstring, and add the feature to - the list in README.rst. diff --git a/{{cookiecutter.project_name}}/README.md b/{{cookiecutter.project_name}}/README.md index e1860be..baabcb4 100644 --- a/{{cookiecutter.project_name}}/README.md +++ b/{{cookiecutter.project_name}}/README.md @@ -15,7 +15,7 @@ First, create a repository on GitHub with the same name as this project, and then run the following commands: -``` bash +```bash git init -b main git add . git commit -m "init commit" @@ -29,29 +29,28 @@ Finally, install the environment and the pre-commit hooks with make install ``` -You are now ready to start development on your project! The CI/CD -pipeline will be triggered when you open a pull request, merge to main, -or when you create a new release. +You are now ready to start development on your project! +The CI/CD pipeline will be triggered when you open a pull request, merge to main, or when you create a new release. -To finalize the set-up for publishing to PyPi or Artifactory, see -[here](https://fpgmaas.github.io/cookiecutter-poetry/features/publishing/#set-up-for-pypi). -For activating the automatic documentation with MkDocs, see -[here](https://fpgmaas.github.io/cookiecutter-poetry/features/mkdocs/#enabling-the-documentation-on-github). +To finalize the set-up for publishing to PyPi or Artifactory, see [here](https://fpgmaas.github.io/cookiecutter-poetry/features/publishing/#set-up-for-pypi). +For activating the automatic documentation with MkDocs, see [here](https://fpgmaas.github.io/cookiecutter-poetry/features/mkdocs/#enabling-the-documentation-on-github). To enable the code coverage reports, see [here](https://fpgmaas.github.io/cookiecutter-poetry/features/codecov/). ## Releasing a new version {% if cookiecutter.publish_to == "pypi" -%} + - Create an API Token on [Pypi](https://pypi.org/). -- Add the API Token to your projects secrets with the name `PYPI_TOKEN` by visiting -[this page](https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/settings/secrets/actions/new). +- Add the API Token to your projects secrets with the name `PYPI_TOKEN` by visiting [this page](https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/settings/secrets/actions/new). - Create a [new release](https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/releases/new) on Github. -Create a new tag in the form ``*.*.*``. +- Create a new tag in the form `*.*.*`. For more details, see [here](https://fpgmaas.github.io/cookiecutter-poetry/features/cicd/#how-to-trigger-a-release). {%- elif cookiecutter.publish_to == "artifactory" -%} + - Add the `ARTIFACTORY_URL`, `ARTIFACTORY_USERNAME`, and `ARTIFACTORY_PASSWORD` to your projects secrets by visiting [this page](https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/settings/secrets/actions/new). -- Create a [new release](https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/releases/new) on Github. Create a new tag in the form ``*.*.*``. +- Create a [new release](https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/releases/new) on Github. +- Create a new tag in the form `*.*.*`. For more details, see [here](https://fpgmaas.github.io/cookiecutter-poetry/features/cicd/#how-to-trigger-a-release). {%- endif %}