You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/CONTRIBUTING.md
+98-28Lines changed: 98 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,18 +7,20 @@ contribution is at its best.
7
7
8
8
## Setting up your Development Environment
9
9
10
+
> [!TIP]
11
+
> If you're using VS Code or Cursor, you can develop inside a container using the provided `.devcontainer` configuration. This provides a pre-configured environment with all dependencies installed. Simply open the project in your editor and select "Reopen in Container" when prompted.
12
+
10
13
Before getting started, you will need to already have installed:
11
14
12
-
- Python (3.8+ only), with development headers installed
@@ -41,18 +43,18 @@ can make changes to the `.py` files and test them without requiring a rebuild
41
43
of msgspec's C extension. Edit away!
42
44
43
45
If you do make changes to a `.c` file, you'll need to recompile. You can do
44
-
this by running
46
+
this by running commands with the `rebuild` variable set to `true` or `1`:
45
47
46
48
```bash
47
-
pip install -e .
49
+
just rebuild=1 test
48
50
```
49
51
50
52
By default `msgspec` is built in release mode, with optimizations enabled. To
51
-
build a debug build instead (for use with e.g. `gdb` or `lldb`) define the
52
-
`MSGSPEC_DEBUG` environment variable before building.
53
+
build a debug build instead (for use with e.g. `gdb` or `lldb`) set the
54
+
`debug`variable to `true` or `1` when running the command:
53
55
54
56
```bash
55
-
MSGSPEC_DEBUG=1 pip install -e .
57
+
just rebuild=1 debug=1 test
56
58
```
57
59
58
60
## Testing
@@ -61,23 +63,36 @@ Tests are located in the `tests/` directory. Any code changes should include
61
63
additional tests to ensure correctness. The tests are broken into various
62
64
`test_*.py` files specific to the functionality that they're testing.
63
65
64
-
The tests can be run using `pytest` as follows:
66
+
The recipes prefixed with `test-` use `pytest` to run the tests. For example:
67
+
68
+
```bash
69
+
just test-all
70
+
```
71
+
72
+
All such recipes accept additional arguments that are passed to `pytest`. For
73
+
example, if you want to run a specific test file:
65
74
66
75
```bash
67
-
pytest
76
+
just test tests/test_json.py
68
77
```
69
78
70
-
If you want to run a specific test file, you may specify that file explicitly:
79
+
To invoke `pytest` directly, you can use the `test-env` recipe:
71
80
72
81
```bash
73
-
pytest tests/test_json.py
82
+
just test-env pytest --help
83
+
```
84
+
85
+
To run tests with a specific version of Python, you can use the `python` variable:
86
+
87
+
```bash
88
+
just python=3.12 test
74
89
```
75
90
76
91
## Linting
77
92
78
-
We use `pre-commit` to automatically run a few code linters before every
79
-
commit. If you followed the development setup above, you should already have
80
-
`pre-commit` and all the commit hooks installed.
93
+
We use [`prek`](https://github.com/j178/prek) to automatically run a few code
94
+
linters before every commit. If you followed the development setup above, you
95
+
should already have `prek` and all the Git hooks installed.
81
96
82
97
These hooks will run whenever you try to commit changes.
83
98
@@ -88,20 +103,75 @@ git commit # linters will run automatically here
88
103
If you wish to run the linters manually without committing, you can run:
89
104
90
105
```bash
91
-
pre-commit run
106
+
just hooks
107
+
```
108
+
109
+
You may also run the same hooks without applying fixes:
110
+
111
+
```bash
112
+
just check
92
113
```
93
114
94
115
## Documentation
95
116
96
117
The source of the documentation can be found under `docs/source/`. They are
97
-
built using `Sphinx` and can be built locally by running the following steps:
118
+
built using `Sphinx` and can be built locally by running:
119
+
120
+
```bash
121
+
just doc-build
122
+
```
123
+
124
+
The built HTML documentation can be served locally by running:
125
+
126
+
```bash
127
+
just doc-serve
128
+
```
129
+
130
+
## Benchmarking
131
+
132
+
To run benchmarks, you can use the `bench-run` recipe:
133
+
134
+
```bash
135
+
just bench-run --libs msgspec
136
+
```
137
+
138
+
To run benchmarks against all libraries, omit the `--libs` argument.
139
+
140
+
## Dev Container
141
+
142
+
You can manually use dev containers as long as the official [`devcontainer`](https://github.com/devcontainers/cli) CLI is on PATH.
143
+
144
+
> [!NOTE]
145
+
> If you need to install the `devcontainer` CLI and don't yet have Node.js installed, the easiest way is to use [`mise`](https://github.com/jdx/mise) (mise-en-place).
0 commit comments