Skip to content

Commit 06a028d

Browse files
mjbearmjbear
authored
Add Makefile for local testing (hellt#21)
* Add Makefile * Update CONTRIBUTING.md with Makefile info * Fix trailing punctuation MD026 in CONTRIBUTING.md * Remove echoing from Makefile * Use Makefile RECIPEPREFIX instead of tabs * Tabs can be a pain to spot * Oftentimes we have our text editors set to convert a tab to spaces * In addtion to RECIPEPREFXI, Was able to add white space to make it reasonably easy to read * Migrate to Docker images for the linting * Switch to astral's ruff Docker image
1 parent 5511f9c commit 06a028d

File tree

3 files changed

+188
-4
lines changed

3 files changed

+188
-4
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,3 +163,6 @@ cython_debug/
163163

164164
# vim
165165
*.swp
166+
167+
# Node.js
168+
node_modules/

‎CONTRIBUTING.md‎

Lines changed: 105 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,21 @@ For minimal dependencies, the "batteries included" [Python `unittest` framework]
3333
is utilized. (Other testing frameworks could be considered should additional
3434
testing features be needed.)
3535

36+
Testing can be invoked via [`make test` (more information below)](#run-python-unit-tests)
37+
38+
## Development Requirements
39+
40+
* Python 3
41+
* GNU Make
42+
* Docker (Engine)
43+
44+
> [!IMPORTANT]
45+
> If your development workstation has a security access control (ex: SELinux)
46+
> enabled, you will need to put it in a permissive mode for the Docker bind
47+
> mounts to function.
48+
3649
## Development Process
3750

38-
>
3951
> This section consists of suggestions.
4052
4153
It is recommended to verify tests are successful before making any code changes.
@@ -48,9 +60,12 @@ code regression.
4860

4961
1. From the `main` branch of your fork, [create a feature branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository)
5062

51-
1. Validate [test cases run successfully](#running-unit-tests) before any
63+
1. Validate [test cases run successfully](#run-python-unit-tests) before any
5264
changes are made
5365

66+
1. Verify [linting and formatting checks run successfully](#run-all-linters-in-one-shot)
67+
before making any changes
68+
5469
1. Make modifications
5570

5671
1. Re-test with the existing unit tests against the modified codebase
@@ -59,12 +74,98 @@ code regression.
5974

6075
1. Re-run the unit tests to confirm they run successfully
6176

77+
1. Re-run linting and formatting checks
78+
79+
1. Fix up any linting or formatting errors
80+
6281
1. When you are satisfied with the changes and it is ready for review,
6382
[submit a Pull Request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
6483

65-
## Running Unit Tests
84+
## Using `make` to streamline linting and testing
85+
86+
This project uses GNU `make` to simplify the action of interacting with several
87+
linters and performing unit testing.
88+
Project dependencies and Python virtual environment are managed with `uv`.
89+
90+
## Prequisites
91+
92+
* Install GNU [`make`](https://www.gnu.org/software/make/) for your operating
93+
system
94+
* Install Docker (Engine)
95+
96+
## General
97+
98+
### Default (all)
99+
100+
* lint and test
101+
102+
```bash
103+
make all
104+
105+
# or simply
106+
make
107+
```
108+
109+
### Clean
110+
111+
* Removes the Docker images this Makefile utilizes
112+
113+
`make clean`
114+
115+
## Linting
116+
117+
### Run all linters in one shot
118+
119+
`make lint`
120+
121+
### Run markdownlint-cli2 for Markdown linting
122+
123+
`make mdlint`
124+
125+
### Run ruff for Python linting
126+
127+
`make ruff`
128+
129+
### Run yamllint for Markdown linting
130+
131+
`make yamllint`
132+
133+
## Testing
134+
135+
### Run Python unit tests
136+
137+
`make test`
138+
139+
## But I want to run linting locally
140+
141+
> [!NOTE]
142+
> This project uses Docker images to avoid shipping or depending on other
143+
> projects, package managers, or languages (Node.js, Ruby).
144+
>
145+
> Non-Dockerized local testing is not supported by the repo owner.
146+
>
147+
> There are extra `make` targets in the Makefile in case you'd prefer local
148+
> linting and formatting.
149+
150+
* Install GNU Make (same requirement as the main development pattern)
151+
* [Install `uv` for Python package management](https://docs.astral.sh/uv/#getting-started)
152+
* Install `npm` for Node.js package management
153+
154+
```bash
155+
make localclean
156+
make localinit
157+
make localmdl
158+
make localruff
159+
make localyaml
160+
```
161+
162+
## Running Unit Tests Manually
163+
164+
> [!NOTE]
165+
> This information is somewhat historical since incorporating the Makefile,
166+
> but could prove useful.
66167
67-
Choose one of the below testing commands methods that suits your needs.
168+
Choose one of the below testing command options that suits your needs.
68169

69170
> [!IMPORTANT]
70171
> The commands below are to be run from the top level of the project.

‎Makefile‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
.RECIPEPREFIX = >
2+
VENV ?= .venv/bin/activate
3+
4+
all: lint test
5+
.PHONY: all
6+
7+
.PHONY: clean
8+
clean:
9+
> @docker rmi ghcr.io/astral-sh/ruff:0.7.2 \
10+
> davidanson/markdownlint-cli2:v0.14.0 \
11+
> cytopia/yamllint
12+
13+
# run all the linting operations
14+
.PHONY: lint
15+
lint: ruff mdlint yamllint
16+
17+
# markdown linting
18+
# Note: Local security access control (ex: SELinux) will temporarily need to
19+
# be disabled for the Docker bind mounts to function.
20+
.PHONY: mdlint
21+
mdlint:
22+
> @docker run --rm -v ${PWD}:/workdir davidanson/markdownlint-cli2:v0.14.0
23+
24+
# Python linting and formatting
25+
.PHONY: ruff
26+
ruff:
27+
> @docker run --rm -v ${PWD}:/workdir ghcr.io/astral-sh/ruff:0.7.2 \
28+
> check /workdir
29+
> @docker run --rm -v ${PWD}:/workdir ghcr.io/astral-sh/ruff:0.7.2 \
30+
> format --check --diff /workdir
31+
32+
# Python unit tests
33+
.PHONY: test
34+
test:
35+
> @python -m unittest discover -s tests -v
36+
37+
# yaml linting
38+
.PHONY: yamllint
39+
yamllint:
40+
> @docker run --rm -v ${PWD}:/data cytopia/yamllint .
41+
42+
43+
### LOCAL DEVELOPMENT ###
44+
# (non-containerized)
45+
46+
# clean up caches (ruff, node, py)
47+
.PHONY: localclean
48+
localclean:
49+
> @rm -rf .venv node_modules .ruff_cache __pycache__ tests/__pycache__
50+
51+
# set up the LOCAL testing environment
52+
.PHONY: localinit
53+
.ONESHELL:
54+
localinit:
55+
> @uv venv
56+
> @source .venv/bin/activate
57+
> @uv pip install ruff yamllint
58+
> @deactivate
59+
> @npm install markdownlint-cli2 --save-dev
60+
61+
# remains as an artifact for those who want to use local linting
62+
# LOCAL markdown linting
63+
.PHONY: localmdl
64+
localmdl:
65+
> @./node_modules/.bin/markdownlint-cli2
66+
67+
# LOCAL Python linting and formatting
68+
.PHONY: localruff
69+
localruff:
70+
> @source $(VENV)
71+
> @uv run ruff check
72+
> @uv run ruff format --check --diff
73+
> @deactivate
74+
75+
# LOCAL yaml linting
76+
.PHONY: localyaml
77+
localyaml:
78+
> @source $(VENV)
79+
> @uv run yamllint .
80+
> @deactivate

0 commit comments

Comments
 (0)