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

Transition tooling to hatch #32

Merged
merged 6 commits into from
Sep 18, 2024
Merged
Show file tree
Hide file tree
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
8 changes: 5 additions & 3 deletions .github/workflows/publish-develop-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,14 @@ jobs:
- uses: actions/setup-python@v5
with:
python-version: 3.x
- run: pip install -r requirements/build-docs.txt
cache: pip
- name: Install dependecies
run: |
pip install --upgrade hatch uv
- name: Publish Develop Docs
run: |
git config user.name github-actions
git config user.email [email protected]
cd docs
mike deploy --push develop
hatch run docs:deploy_develop
concurrency:
group: publish-docs
13 changes: 8 additions & 5 deletions .github/workflows/publish-py.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,17 @@ jobs:
uses: actions/setup-python@v5
with:
python-version: "3.x"
- name: Install dependencies
cache: pip
- name: Install dependecies
run: |
python -m pip install --upgrade pip
pip install -r requirements/build-src.txt
- name: Build and publish
pip install --upgrade hatch uv
- name: Build
run: |
hatch build --clean
# TODO: Update trusted publishing with pypa/gh-action-pypi-publish
Copy link
Owner

@Archmonger Archmonger Sep 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't mind making the switch to pypa/gh-action-pypi-publish within this PR, since we're already touching this file anyways

EDIT: Looks like there might be a bit that goes into getting that workflow running - We can skip it for now if it's too involved.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it would take some work on PyPi (https://docs.pypi.org/trusted-publishers/).

I was thinking to do that in a separate PR, this on was growing enough already! Perhaps doing some updates to create a GitHub release with artifacts, publish, etc, on the creation of a semver tag? Since this uses Keep a Changelog, even that can be pulled out automatically and added to the release

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As an idea of how I suggest updating the actions, I use this flow: https://github.com/stumpylog/gotenberg-client/actions/runs/10653499633

Basically, the checks like tests, documentation and building a wheel/sdist always run, then a release to Github and Pypi run when a tag is created to do those only on a tag. This would also include publishing the versioned documentation.

If that sounds alright, I'm happy to work on it (in a separate PR)

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unless I'm misunderstanding your comment, that is effectively what is currently being done in this repo but in an event driven fashion rather than polling on each merge.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You still need to manually create the release, attach artifacts and update the change log right? I don't see anything handling that.

My own preference is to simply push a tag and let the jobs handle that based on what was pushed, and only after that double check of testing, building, etc

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahhh okay I understand your point - Yeah manually creating the GH releases is unnecessary manual labor. If we can automate that would be fantastic.

- name: Publish
env:
TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
run: |
python -m build --sdist --wheel --outdir dist .
twine upload dist/*
8 changes: 5 additions & 3 deletions .github/workflows/publish-release-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,14 @@ jobs:
- uses: actions/setup-python@v5
with:
python-version: 3.x
- run: pip install -r requirements/build-docs.txt
cache: pip
- name: Install dependecies
run: |
pip install --upgrade hatch uv
- name: Publish ${{ github.event.release.name }} Docs
run: |
git config user.name github-actions
git config user.email [email protected]
cd docs
mike deploy --push --update-aliases ${{ github.event.release.name }} latest
hatch run docs:deploy_latest ${{ github.event.release.name }}
concurrency:
group: publish-docs
16 changes: 9 additions & 7 deletions .github/workflows/test-docs.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: Test
name: Test Docs

on:
pull_request:
Expand All @@ -17,11 +17,13 @@ jobs:
- uses: actions/setup-python@v5
with:
python-version: 3.x
cache: pip
- name: Install dependecies
run: |
pip install --upgrade hatch uv
- name: Check documentation links
run: |
hatch run docs:linkcheck
- name: Check docs build
run: |
pip install -r requirements/build-docs.txt
linkcheckMarkdown docs/ -v -r
linkcheckMarkdown README.md -v -r
linkcheckMarkdown CHANGELOG.md -v -r
cd docs
mkdocs build --strict
hatch run docs:build
31 changes: 18 additions & 13 deletions .github/workflows/test-src.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: Test
name: Test Code

on:
push:
Expand Down Expand Up @@ -36,22 +36,26 @@ jobs:
python-version: ${{ matrix.python-version }}
allow-prereleases: true
cache: pip
cache-dependency-path: "requirements/*.txt"

- name: Install dependencies
run: |
python -m pip install --upgrade pip setuptools wheel
python -m pip install --upgrade 'tox>=4.0.0rc3'
python -m pip install --upgrade pip hatch uv

- name: Run tox targets for ${{ matrix.python-version }}
run: tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
- name: Show environment
run: |
hatch test --show --python ${{ matrix.python-version }}

- name: Run tests
run: |
hatch test --cover --python ${{ matrix.python-version }}
mv .coverage ".coverage.py${{ matrix.python-version }}"

- name: Upload coverage data
if: matrix.os != 'windows-latest'
uses: actions/upload-artifact@v3
uses: actions/upload-artifact@v4
with:
name: coverage-data
path: ".coverage.*"
name: "coverage-data-py${{ matrix.python-version }}"
path: ".coverage.py${{ matrix.python-version }}"
if-no-files-found: error
include-hidden-files: true

Expand All @@ -65,24 +69,25 @@ jobs:
- uses: actions/setup-python@v5
with:
python-version: "3.11"
cache: pip

- name: Install dependencies
run: python -m pip install --upgrade coverage[toml]

- name: Download data
uses: actions/download-artifact@v3
uses: actions/download-artifact@v4
with:
name: coverage-data
merge-multiple: true

- name: Combine coverage and fail if it's <100%
- name: Combine coverage and fail if it's <95%
run: |
python -m coverage combine
python -m coverage html --skip-covered --skip-empty
python -m coverage report --fail-under=95

- name: Upload HTML report
if: ${{ failure() }}
uses: actions/upload-artifact@v3
uses: actions/upload-artifact@v4
with:
name: html-report
path: htmlcov
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,9 @@ coverage.xml
*.cover
.hypothesis/

# Linter cache
.ruff_cache/

# Jupyter Notebook
.ipynb_checkpoints

Expand All @@ -96,6 +99,7 @@ venv.bak/

# mkdocs documentation
/site
/docs/site/

# mypy
.mypy_cache/
Expand Down
7 changes: 0 additions & 7 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -1,6 +1,3 @@
default_language_version:
python: python3.12

repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.6.0
Expand All @@ -17,10 +14,6 @@ repos:
rev: 1.8.0
hooks:
- id: pyproject-fmt
- repo: https://github.com/tox-dev/tox-ini-fmt
rev: 1.3.1
hooks:
- id: tox-ini-fmt
- repo: https://github.com/rstcheck/rstcheck
rev: v6.2.0
hooks:
Expand Down
4 changes: 1 addition & 3 deletions docs/mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,7 @@ nav:
- FAQ: django-faq.md
- About:
- Changelog: changelog.md
# - Contributor Guide:
# - Code: about/code.md
# - Docs: about/docs.md
- Contributor Guide: contributing.md
- Community:
- GitHub Discussions: https://github.com/Archmonger/ServeStatic/discussions
- License: license.md
Expand Down
112 changes: 112 additions & 0 deletions docs/src/contributing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# Contributing

## Tool Setup

### `python`

To contribute code or documentation updates, an installation of Python 3 is required.

### `hatch`

This project utilizes [`hatch`](https://hatch.pypa.io/latest/) to manage Python environments for development and testing. Follow
[the `hatch` installation instructions](https://hatch.pypa.io/latest/install/) before continuing through this document.

### `pre-commit`

Additionally, this project uses [`pre-commit`](https://pre-commit.com/) Git hooks to run linting and formatting checks against each commit. See [the `pre-commit` installation instructions](https://pre-commit.com/#install) for how to install this tool.

Once installed, run `pre-commit install` to set up the git hook scripts:
Archmonger marked this conversation as resolved.
Show resolved Hide resolved

``` shell
$ pre-commit install
pre-commit installed at .git/hooks/pre-commit
```

### Git

Clone the repository using:

``` shell
git clone https://github.com/Archmonger/ServeStatic.git
cd ServeStatic
```

All example commands are expected to be run from the `ServeStatic` folder.

## Code Contributions

Ensure you have followed the [tool setup](#tool-setup) instructions before following the instructions below.

### Development

#### Linting

The project uses `flake8` and `isort` for linting and uses `black` to format code. To run the all linters:

``` shell
hatch run lint:check
```

Or select a specific linter:

``` shell
hatch run lint:flake8
```

!!! tip

Linting is likely to see an update in the near future to use `ruff` for linting and formatting.

### Testing

Tests are run across a matrix of Python and Django versions to ensure full compatibility with all supported versions.

#### Full Test Suite

To run the full test suite, using the system Python:

``` shell
hatch test
```

To select a particular Python version:

``` shell
hatch test --python 3.9
```

!!! tip

`hatch` can manage Python versions for you, for example installing Python 3.9: `hatch python install 3.9`

See the [hatch documentation](https://hatch.pypa.io/latest/tutorials/python/manage/)

To select a particular Django version:

``` shell
hatch test --include "django=5.1"
```

#### Specific Test(s)

To run only a specific test:

``` shell
hatch test -k test_get_js_static_file
```

!!! tip

Additional arguments are passed on to pytest.

See the [pytest documentation](https://docs.pytest.org/en/8.3.x/reference/reference.html#command-line-flags) for options

## Documentation Contributions

Ensure you have followed the [tool setup](#tool-setup) instructions before following the instructions below.

### Modifying Documentation

1. Start the `mkdocs` server by running `hatch run docs:serve`
1. Visit [the documentation site](http://localhost:8000/) in your preferred browser
1. Edit the documentation. The site will load change as documentation files change.
4 changes: 4 additions & 0 deletions docs/src/dictionary.txt
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,7 @@ sublicense
middleware
unhashed
async
linter
linters
linting
pytest
Loading