1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
# Contributing
:tada: Thanks for taking the time to contribute! :tada:
The following is a set of guidelines for contributing to [syrupy](https://github.com/syrupy-project/syrupy).
These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document.
## Table Of Contents
[Code of Conduct](#code-of-conduct)
[What should I know before I get started?](#what-should-i-know-before-i-get-started)
- [Python 3](#python-3)
- [Snapshot Testing](#snapshot-testing)
- [Releases](#releases)
[How Can I Contribute?](#how-can-i-contribute)
- [Reporting Bugs](#reporting-bugs)
- [Suggesting Enhancements](#suggesting-enhancements)
- [Your First Code Contribution](#your-first-code-contribution)
- [Pull Requests](#pull-requests)
- [Debugging](#debugging)
[Styleguides](#styleguides)
- [Commit Messages](#commit-messages)
- [Code Styleguide](#code-styleguide)
- [`pathlib` over `os.path`](#usage-of-pathlib)
[Additional Notes](#additional-notes)
- [Issue and Pull Request Labels](#issue-and-pull-request-labels)
## Code of Conduct
This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
## What should I know before I get started
### Python 3
- Python typing and hints: [typing](https://docs.python.org/3/library/typing.html)
### Snapshot Testing
- Javascript snapshot testing [jest](https://jestjs.io/docs/en/snapshot-testing)
### Releases
- Semantic versioning: [semver](https://semver.org/spec/v2.0.0.html)
## How Can I Contribute
Before diving into writing code, please take a look at the following.
### Reporting Bugs
When attempting to fix a bug, create an issue using the "Bug report" template.
Give as much information in this issue as it allows for discussions and documentation about the decisions reached for any bugs that have been encounted.
### Suggesting Enhancements
Have an idea? Create an issue using the "Feature request" template.
Detailing in there as much as possible, the idea and any potential solutions to it, before suggesting a pull request.
### Your First Code Contribution
Have an issue to submit code changes for? See below.
#### Local development
- Clone the repository
- Run `. script/bootstrap` to ensure you're working from the correct environment
- Run `inv test` to verify enviroment is correctly setup
- Checkout a new branch and add code changes
- Add tests to verify code changes and rerun `inv test`
- See submitting [pull requests](#pull-requests)
### Pull Requests
Creating a pull request uses our template using the GitHub web interface.
Fill in the relevant sections, clearly linking the issue the change is attemping to resolve.
### Debugging
`debugpy` is installed in local development. A VSCode launch config is provided. Run `inv test -v -d` to enable the debugger (`-d` for debug). It'll then wait for you to attach your VSCode debugging client.
#### Debugging Performance Issues
You can run `inv benchmark` to run the full benchmark suite. Alternatively, write a test file, e.g.:
```py
# test_performance.py
import pytest
import os
SIZE = int(os.environ.get("SIZE", 1000))
@pytest.mark.parametrize("x", range(SIZE))
def test_performance(x, snapshot):
assert x == snapshot
```
and then run:
```sh
SIZE=1000 python -m cProfile -s cumtime -m pytest test_performance.py --snapshot-update -s > profile.log
```
See the cProfile docs for metric sorting options.
## Styleguides
### Commit Messages
Provide semantic commit messages following this [convention](https://www.conventionalcommits.org/en/v1.0.0/#summary).
This informs the semantic versioning we use to control our [releases](#releases).
### Code Styleguide
A linter is available to catch most of our styling concerns.
This is provided in a pre-commit hook when setting up [local development](#local-development).
You can also run `inv lint --fix` to see and solve what issues it can.
### Usage of Pathlib
`pathlib` is the preferred library when dealing with path operations. Some [documentation](https://docs.python.org/3/library/pathlib.html#correspondence-to-tools-in-the-os-module) is available to help translate `os.path`-type calls to `pathlib` calls. Documentation on `pathlib`'s API is also available on the same page.
## Additional Notes
### Issue and Pull Request Labels
Please tag issues and pull requests according to the relevant [github labels](https://github.com/syrupy-project/syrupy/issues/labels).
|
