Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add tooling install instructions to contributor guide #51

Merged
merged 2 commits into from
Jan 25, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 43 additions & 20 deletions {{cookiecutter.project_name}}/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,6 @@ Here is a list of important resources for contributors:
- [Issue Tracker]
- [Code of Conduct]

[{{cookiecutter.license.replace("-", " ").lower()}} license]: https://opensource.org/licenses/{{cookiecutter.license}}
[source code]: https://github.com/{{cookiecutter.github_organization}}/{{cookiecutter.project_name}}
[documentation]: https://{{cookiecutter.github_organization}}.github.io/{{cookiecutter.project_name}}
[issue tracker]: https://github.com/{{cookiecutter.github_organization}}/{{cookiecutter.project_name}}/issues

## How to report a bug

Report bugs on the [Issue Tracker].
Expand Down Expand Up @@ -43,50 +38,69 @@ You need Python 3.9+ and the following tools:
- [Nox]
- [nox-poetry]

Install the package with development requirements:
Install [pipx]:

```console
$ poetry install
python -m pip install --user pipx
python -m pipx ensurepath
```

You can now run an interactive Python session,
or the command-line interface:
Install [Poetry]:

```console
$ poetry run python
$ poetry run {{cookiecutter.project_name}}
pipx install poetry
```

[poetry]: https://python-poetry.org/
[nox]: https://nox.thea.codes/
[nox-poetry]: https://nox-poetry.readthedocs.io/
Install [Nox] and [nox-poetry]:

```console
pipx install nox
pipx inject nox nox-poetry
```

Install the pre-commit hooks

```console
nox --session=pre-commit -- install
```

Install the package with development requirements:

```console
poetry install
```

You can now run an interactive Python session, or your app:

```console
poetry run python
poetry run {{cookiecutter.project_name}}
```

## How to test the project

Run the full test suite:

```console
$ nox
nox
```

List the available Nox sessions:

```console
$ nox --list-sessions
nox --list-sessions
```

You can also run a specific Nox session.
For example, invoke the unit test suite like this:

```console
$ nox --session=tests
nox --session=tests
```

Unit tests are located in the _tests_ directory,
and are written using the [pytest] testing framework.

[pytest]: https://pytest.readthedocs.io/

## How to submit changes

Open a [pull request] to submit changes to this project.
Expand All @@ -102,12 +116,21 @@ Feel free to submit early, though—we can always iterate on this.
To run linting and code formatting checks before committing your change, you can install pre-commit as a Git hook by running the following command:

```console
$ nox --session=pre-commit -- install
nox --session=pre-commit -- install
```

It is recommended to open an issue before starting work on anything.
This will allow a chance to talk it over with the owners and validate your approach.

[{{cookiecutter.license.replace("-", " ").lower()}} license]: https://opensource.org/licenses/{{cookiecutter.license}}
[source code]: https://github.com/{{cookiecutter.github_organization}}/{{cookiecutter.project_name}}
[documentation]: https://{{cookiecutter.github_organization}}.github.io/{{cookiecutter.project_name}}
[issue tracker]: https://github.com/{{cookiecutter.github_organization}}/{{cookiecutter.project_name}}/issues
[pipx]: https://pipx.pypa.io/
[poetry]: https://python-poetry.org/
[nox]: https://nox.thea.codes/
[nox-poetry]: https://nox-poetry.readthedocs.io/
[pytest]: https://pytest.readthedocs.io/
[pull request]: https://github.com/{{cookiecutter.github_organization}}/{{cookiecutter.project_name}}/pulls

<!-- github-only -->
Expand Down
Loading