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: CONTRIBUTING.md
+35-20Lines changed: 35 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,22 +10,23 @@ Please check out the [the open issues](https://github.com/drwpow/openapi-typescr
10
10
11
11
Contributing doesn’t have to be in code! Simply answering questions in open issues, or providing workarounds, is just as important a contribution as making pull requests.
12
12
13
-
## Setup
13
+
## Opening a Pull Request
14
14
15
-
### Dependencies
15
+
Pull requests are **welcome** for this repo! Bugfixes will always be accepted, though in some cases some small changes may be requested.
16
+
17
+
However, if adding a feature or breaking change, please **open an issue first to discuss.** This ensures no time or work is wasted writing code that won’t be accepted to the project (see [Project Goals](./README.md#-project-goals)). Undiscussed feature work may be rejected at the discretion of the maintainers.
18
+
19
+
### Setup
16
20
17
21
1. Install [pnpm](https://pnpm.io/)
18
-
2. Fork and clone the repo
22
+
2.[Fork this repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo)and clone your copy locally
19
23
3. Run `pnpm i` to install dependencies
20
-
4. Create a branch for your PR with `git checkout -b pr/your-branch-name`
21
24
22
-
### VS Code setup
25
+
### Writing code
23
26
24
-
If using VS Code, the following extensions are recommended (or their equivalent extensions if using another editor)
27
+
Create a new branch for your PR with `git checkout -b your-branch-name`. Add the relevant code as well as docs and tests. When you push everything up (`git push`), navigate back to your repo GitHub and you should see a prompt to open a new PR.
While best practices for commit messages are encouraged (e.g. start with an imperative verb, keep it short, use the body if needed), this repo doesn’t follow any specific guidelines like [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). Clarity is favored over strict rules. Changelogs are generated separately from git (see [the Changelogs section](#changelogs)
29
30
30
31
When working locally, run:
31
32
@@ -35,6 +36,10 @@ npm run dev
35
36
36
37
This will compile the code as you change automatically.
37
38
39
+
### Writing the PR
40
+
41
+
**Please fill out the template!** It’s a very lightweight template 🙂.
42
+
38
43
### TDD
39
44
40
45
This library is a great usecase for [test-driven development (TDD)](https://en.wikipedia.org/wiki/Test-driven_development). If you’re new to this, the basic workflow is:
@@ -45,16 +50,6 @@ This library is a great usecase for [test-driven development (TDD)](https://en.w
45
50
46
51
_Code generation is hard!_ And for that reason, starting with a very clear expectation of your end-goal can make working easier.
47
52
48
-
### Unit tests or snapshot tests?
49
-
50
-
This library has both unit tests (tests that test a tiny part of a schema) and snapshot tests (tests that run over an entire, complete schema). When opening a PR, the former are more valuable than the latter, and are always required. However, updating snapshot tests can help with the following:
51
-
52
-
- Fixing bugs that deal with multiple schemas with remote `$ref`s
53
-
- Fixing Node.js or OS-related bugs
54
-
- Adding a CLI option that changes the entire output
55
-
56
-
For most PRs, **snapshot tests can be avoided.** But for scenarios similar to the ones mentioned, they can ensure everything is working as expected.
57
-
58
53
#### Updating snapshot tests
59
54
60
55
To add a schema as a snapshot test, modify the [/scripts/download-schemas.ts](/scripts/download-schemas.ts) script with a path to download. There are both single-file schemas as well as multi-file schemas.
@@ -76,6 +71,16 @@ When opening a pull request, make sure all of the following is done:
76
71
77
72
Lastly, be sure to fill out the complete PR template!
78
73
74
+
### Changelogs
75
+
76
+
The changelog is generated via [changesets](https://github.com/changesets/changesets), and is separate from Git commit messages and pull request titles. To write a human-readable changelog for your changes, run:
77
+
78
+
```
79
+
npx changeset
80
+
```
81
+
82
+
This will ask if it’s a `patch`, `minor`, or `major` change ([semver](https://semver.org/)), along with a plain description of what you did. Commit this new file along with the rest of your PR, and during the next release this will go into the official changelog!
83
+
79
84
## Testing
80
85
81
86
This library uses [Vitest](https://vitest.dev/) for testing. There’s a great [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ZixuanChen.vitest-explorer) you can optionally use if you’d like in-editor debugging tools.
@@ -93,7 +98,7 @@ npm test
93
98
To run an individual test:
94
99
95
100
```bash
96
-
npx vitest [partial filename]
101
+
npm test -- [partial filename]
97
102
```
98
103
99
104
To start the entire test suite in watch mode:
@@ -117,3 +122,13 @@ npm run lint
117
122
```bash
118
123
npm run update:examples
119
124
```
125
+
126
+
### Unit tests or snapshot tests?
127
+
128
+
This library has both unit tests (tests that test a tiny part of a schema) and snapshot tests (tests that run over an entire, complete schema). When opening a PR, the former are more valuable than the latter, and are always required. However, updating snapshot tests can help with the following:
129
+
130
+
- Fixing bugs that deal with multiple schemas with remote `$ref`s
131
+
- Fixing Node.js or OS-related bugs
132
+
- Adding a CLI option that changes the entire output
133
+
134
+
For most PRs, **snapshot tests can be avoided.** But for scenarios similar to the ones mentioned, they can ensure everything is working as expected.
0 commit comments