Skip to content

Commit c9a032b

Browse files
audreyfeldroyaudreyfeldroy
committed
Set contributor expectations for a zero-dependency ASGI library
CONTRIBUTING.md is rewritten from scratch for this project. It explains the zero-dependency constraint, how tests work at the raw ASGI protocol level, and what "tight and atomic" means for AI- assisted contributions. Installation docs trimmed to the three commands people actually run.
1 parent 46724fd commit c9a032b

2 files changed

Lines changed: 45 additions & 116 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 41 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,137 +1,81 @@
11
# Contributing
22

3-
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
3+
Staticware is about 270 lines of production code. You can read the entire middleware in one sitting, and that's intentional. Contributions that keep the project small and focused are the ones that land.
44

5-
You can contribute in many ways:
5+
## Understanding the Project
66

7-
## Types of Contributions
7+
Before contributing, read `src/staticware/middleware.py`. The whole thing. It's two classes, a couple of helpers, and zero runtime dependencies. The zero-dependency constraint is a design choice: every ASGI framework already has enough dependencies. Staticware should not add to the pile.
88

9-
### Report Bugs
9+
The test suite at `tests/test_staticware.py` talks directly to the ASGI protocol. Tests construct scope dicts, call the middleware, and collect `send()` messages. No framework test client, no HTTP library. If you're adding a feature, your test should work at the same level.
1010

11-
Report bugs at https://github.com/feldroy/staticware/issues.
11+
## What We're Looking For
1212

13-
If you are reporting a bug, please include:
13+
Bug reports, test cases, docs improvements, and features that fit the project's scope. File issues and pull requests at https://github.com/feldroy/staticware/issues.
1414

15-
- Your operating system name and version.
16-
- Any details about your local setup that might be helpful in troubleshooting.
17-
- Detailed steps to reproduce the bug.
15+
If you're proposing a feature, open an issue first. Describe what it does and why it belongs in a static file middleware. Not everything does, and that's fine.
1816

19-
### Fix Bugs
17+
## AI Contributions
2018

21-
Look through the GitHub issues for bugs. Anything tagged with "bug" and "help wanted" is open to whoever wants to implement it.
19+
AI-assisted contributions are welcome. AI-generated slop is not.
2220

23-
### Implement Features
21+
If you use an AI tool to write code for this project, you are responsible for every line it produces. Review it the way you'd review a junior developer's pull request: check the logic, verify the tests actually test what they claim, and make sure the commit messages explain the why, not just the what.
2422

25-
Look through the GitHub issues for features. Anything tagged with "enhancement" and "help wanted" is open to whoever wants to implement it.
23+
Specific expectations:
2624

27-
### Write Documentation
25+
- **Tight.** No boilerplate, no placeholder comments, no "Replace this with..." stubs. If the AI generated scaffolding, strip it before submitting.
26+
- **Atomic.** One logical change per commit. If your PR touches the middleware and the docs and the CI config, those should be separate commits with separate messages.
27+
- **Tested.** Red/green TDD: write a failing test, then write the code that makes it pass. If you can't write the failing test first, you probably don't understand the change well enough yet.
2828

29-
Staticware 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.
30-
31-
To preview the docs locally:
29+
## Development Setup
3230

3331
```sh
34-
just docs-serve
32+
git clone git@github.com:your_name_here/staticware.git
33+
cd staticware/
34+
uv sync
3535
```
3636

37-
This starts a local server at http://localhost:8000 with live reload. Edit files in `docs/` or add docstrings to your code (the API reference page is auto-generated).
38-
39-
### Submit Feedback
40-
41-
The best way to send feedback is to file an issue at https://github.com/feldroy/staticware/issues.
42-
43-
If you are proposing a feature:
44-
45-
- Explain in detail how it would work.
46-
- Keep the scope as narrow as possible, to make it easier to implement.
47-
- Remember that this is a volunteer-driven project, and that contributions are welcome :)
48-
49-
## Get Started!
50-
51-
Ready to contribute? Here's how to set up `staticware` for local development.
52-
53-
1. Fork the `staticware` repo on GitHub.
54-
2. Clone your fork locally:
55-
56-
```sh
57-
git clone git@github.com:your_name_here/staticware.git
58-
```
59-
60-
3. Install your local copy with uv:
61-
62-
```sh
63-
cd staticware/
64-
uv sync
65-
```
66-
67-
4. Create a branch for local development:
68-
69-
```sh
70-
git checkout -b name-of-your-bugfix-or-feature
71-
```
72-
73-
Now you can make your changes locally.
37+
Run the full quality suite (format, lint, type check, test):
7438

75-
5. When you're done making changes, check that your changes pass linting and the tests:
76-
77-
```sh
78-
just qa
79-
```
39+
```sh
40+
just qa
41+
```
8042

81-
Or run the tests alone:
43+
Run tests alone:
8244

83-
```sh
84-
just test
85-
```
86-
87-
6. Commit your changes and push your branch to GitHub:
45+
```sh
46+
just test
47+
```
8848

89-
```sh
90-
git add .
91-
git commit -m "Your detailed description of your changes."
92-
git push origin name-of-your-bugfix-or-feature
93-
```
49+
Preview docs locally:
9450

95-
7. Submit a pull request through the GitHub website.
51+
```sh
52+
just docs-serve
53+
```
9654

9755
## Pull Request Guidelines
9856

99-
Before you submit a pull request, check that it meets these guidelines:
100-
101-
1. The pull request should include tests.
102-
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.
103-
3. The pull request should work for Python 3.12, 3.13, and 3.14. Tests run in GitHub Actions on every pull request to the main branch, make sure that the tests pass for all supported Python versions.
104-
105-
## Tips
106-
107-
To run a subset of tests:
108-
109-
```sh
110-
uv run pytest tests/
111-
```
57+
1. Include tests. The coverage threshold is 90% and the project currently sits at 98%.
58+
2. If you add functionality, update the docs and the README features list.
59+
3. Tests must pass on Python 3.12, 3.13, and 3.14. CI runs automatically on every PR.
11260

113-
## Releasing a New Version
61+
## Releasing
11462

115-
1. **Bump the version** and **write the changelog:**
63+
1. Bump the version:
11664
```bash
11765
uv version <version> # or: uv version --bump minor
11866
```
119-
Then write `CHANGELOG/<version>.md`. See previous entries for the format.
120-
2. **Commit:**
67+
Then write `CHANGELOG/<version>.md`.
68+
2. Commit:
12169
```bash
12270
git add pyproject.toml uv.lock CHANGELOG/
12371
git commit -m "Release <version>"
12472
```
125-
3. **Tag and push:**
73+
3. Tag and push:
12674
```bash
12775
just tag
12876
```
129-
This creates an annotated `v*` tag from the version in `pyproject.toml`
130-
and pushes the commit and tag to GitHub.
131-
4. **Wait for the publish workflow.** The tag triggers `.github/workflows/publish.yml`,
132-
which builds the package, generates SLSA provenance attestations, and publishes
133-
to PyPI via trusted publishing.
134-
5. **Create the GitHub Release:**
77+
4. Wait for the publish workflow to build, attest, and publish to PyPI.
78+
5. Create the GitHub Release:
13579
```bash
13680
gh release create v<version> --verify-tag \
13781
--title "Staticware <version>" \
@@ -140,4 +84,4 @@ uv run pytest tests/
14084

14185
## Code of Conduct
14286

143-
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
87+
This project follows the [Contributor Code of Conduct](CODE_OF_CONDUCT.md).

‎docs/installation.md‎

Lines changed: 4 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,23 @@
11
# Installation
22

3-
## Stable release
4-
5-
To install Staticware, run this command in your terminal:
3+
## With uv
64

75
```sh
86
uv add staticware
97
```
108

11-
Or if you prefer to use `pip`:
9+
## With pip
1210

1311
```sh
1412
pip install staticware
1513
```
1614

17-
## From source
18-
19-
The source files for Staticware can be downloaded from the [Github repo](https://github.com/feldroy/staticware).
15+
## From Source
2016

21-
You can either clone the public repository:
17+
Clone the repo and install in development mode:
2218

2319
```sh
2420
git clone https://github.com/feldroy/staticware
25-
```
26-
27-
Or download the [tarball](https://github.com/feldroy/staticware/tarball/main):
28-
29-
```sh
30-
curl -OJL https://github.com/feldroy/staticware/tarball/main
31-
```
32-
33-
Once you have a copy of the source, you can install it with:
34-
35-
```sh
3621
cd staticware
3722
uv sync
3823
```

0 commit comments

Comments
 (0)