Skip to content

Commit 53b9aab

Browse files
committed
Add GitHub contribution docs
1 parent 80ebeb9 commit 53b9aab

5 files changed

Lines changed: 132 additions & 0 deletions

File tree

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
name: Bug report
3+
about: Report a problem with the site or runner
4+
title: "Bug: "
5+
labels: bug
6+
assignees: ""
7+
---
8+
9+
## What happened?
10+
11+
## Expected behavior
12+
13+
## Page URL
14+
15+
## Browser / environment
16+
17+
## Additional details
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
name: Example improvement
3+
about: Suggest a correction or improvement to an example
4+
title: "Improve example: "
5+
labels: example
6+
assignees: ""
7+
---
8+
9+
## Example
10+
11+
<!-- e.g. /examples/classes -->
12+
13+
## Issue
14+
15+
<!-- What is confusing, incorrect, or missing? -->
16+
17+
## Suggested change
18+
19+
<!-- Optional: propose wording or code/output changes. -->

.github/pull_request_template.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
## Summary
2+
3+
<!-- What changed? -->
4+
5+
## Verification
6+
7+
- [ ] `make verify`
8+
- [ ] `scripts/check_example_migration_parity.py`
9+
- [ ] `scripts/format_examples.py --check`
10+
- [ ] `make verify-python-version VERSION=3.13`
11+
- [ ] `git diff --check`
12+
13+
## Example changes
14+
15+
If this changes examples:
16+
17+
- [ ] Updated files under `src/example_sources/*.md`
18+
- [ ] Kept exactly one `:::program` block per example
19+
- [ ] Kept `:::cell` source/output deterministic and executable
20+
- [ ] Ran `make verify-examples`
21+
- [ ] Ran `make check-generated`

CONTRIBUTING.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Contributing
2+
3+
Thanks for helping improve Python By Example.
4+
5+
## Editing examples
6+
7+
Examples live in:
8+
9+
```text
10+
src/example_sources/*.md
11+
```
12+
13+
Each example has:
14+
15+
- TOML frontmatter with `slug`, `title`, `section`, `summary`, and `doc_path`
16+
- exactly one `:::program` block with the full editable program
17+
- one or more `:::cell` blocks with prose, Python source, and expected output
18+
- optional `:::note` blocks
19+
20+
Use `doc_path`, not full versioned Python docs URLs. The active docs version comes from:
21+
22+
```text
23+
src/example_sources/manifest.toml
24+
```
25+
26+
Do not edit generated files by hand:
27+
28+
```text
29+
src/example_sources_data.py
30+
src/asset_manifest.py
31+
public/*.css/js fingerprinted copies
32+
```
33+
34+
Regenerate them with:
35+
36+
```bash
37+
make build
38+
```
39+
40+
## Before opening a pull request
41+
42+
Start the local Worker for browser-backed checks:
43+
44+
```bash
45+
uv run --group workers pywrangler dev --port 9696
46+
```
47+
48+
Then run:
49+
50+
```bash
51+
make verify
52+
scripts/check_example_migration_parity.py
53+
scripts/format_examples.py --check
54+
make verify-python-version VERSION=3.13
55+
git diff --check
56+
```
57+
58+
For example-only changes, also run:
59+
60+
```bash
61+
make verify-examples
62+
make check-generated
63+
```
64+
65+
## Style expectations
66+
67+
- Keep examples compact and language-tour focused.
68+
- Prefer practical names and output that proves the concept.
69+
- Keep source/output cells executable and deterministic.
70+
- Do not add task-cookbook examples to the language tour.
71+
- Link to official Python 3.13 documentation through `doc_path`.

README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,10 @@ make deploy
153153

154154
`make deploy` runs `make build` first, so embedded example data and cache fingerprints are regenerated before Wrangler deploys.
155155

156+
## Contributing
157+
158+
See `CONTRIBUTING.md` for pull request workflow, example editing rules, and verification commands.
159+
156160
## Updating examples or Python version
157161

158162
Edit Markdown files under `src/example_sources/`.

0 commit comments

Comments
 (0)