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
+92-28Lines changed: 92 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,30 @@ 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
74
83
```
75
84
76
85
## Linting
77
86
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.
87
+
We use [`prek`](https://github.com/j178/prek) to automatically run a few code
88
+
linters before every commit. If you followed the development setup above, you
89
+
should already have `prek` and all the Git hooks installed.
81
90
82
91
These hooks will run whenever you try to commit changes.
83
92
@@ -88,20 +97,75 @@ git commit # linters will run automatically here
88
97
If you wish to run the linters manually without committing, you can run:
89
98
90
99
```bash
91
-
pre-commit run
100
+
just hooks
101
+
```
102
+
103
+
You may also run the same hooks without applying fixes:
104
+
105
+
```bash
106
+
just check
92
107
```
93
108
94
109
## Documentation
95
110
96
111
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:
112
+
built using `Sphinx` and can be built locally by running:
113
+
114
+
```bash
115
+
just doc-build
116
+
```
117
+
118
+
The built HTML documentation can be served locally by running:
119
+
120
+
```bash
121
+
just doc-serve
122
+
```
123
+
124
+
## Benchmarking
125
+
126
+
To run benchmarks, you can use the `bench-run` recipe:
98
127
99
128
```bash
100
-
cd docs/ # Make sure we are in the docs/ folder
129
+
just bench-run --libs msgspec
130
+
```
131
+
132
+
To run benchmarks against all libraries, omit the `--libs` argument.
133
+
134
+
## Dev Container
135
+
136
+
You can manually use dev containers as long as the official [`devcontainer`](https://github.com/devcontainers/cli) CLI is on PATH.
137
+
138
+
> [!NOTE]
139
+
> 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