Skip to content

Commit 3dc2f6d

Browse files
HappyZombiesHappyZombies
authored
Merge pull request #18 from node-oauth/contribution-guidelines
Contribution guidelines
2 parents 8bb0dcc + fcec276 commit 3dc2f6d

File tree

3 files changed

+236
-8
lines changed

3 files changed

+236
-8
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
<!-- ---------------------------------------------------------------------------
2+
3+
🎉 THANK YOU FOR YOUR CONTRIBUTION! 🎉
4+
5+
We highly appreciate your time and effort to this project!
6+
7+
8+
⚠ PLEASE READ THIS FIRST ⚠
9+
10+
1. If this is a fix for a security vulnerability you discovered please don't
11+
just open this PR until we have privately discussed the vulnerability. Disclosing
12+
it without contacting us can lead to severe implications for many applications
13+
that run on this project.
14+
15+
2. Make sure you have read the contribution guidelines for this project in
16+
order to raise the chance of getting your PR accepted. This saves you valuable
17+
time and effort.
18+
19+
3. The following structure is a basic guideline. If a section does not apply you
20+
can remove it.
21+
---------------------------------------------------------------------------- -->
22+
23+
## Summary
24+
<!-- ---------------------------------------------------------------------------
25+
⚠ Provide one or two paragraphs
26+
---------------------------------------------------------------------------- -->
27+
28+
29+
30+
## Linked issue(s)
31+
<!-- ---------------------------------------------------------------------------
32+
⚠ If there is no issue for this PR we won't review it
33+
---------------------------------------------------------------------------- -->
34+
35+
36+
37+
## Involved parts of the project
38+
<!-- ---------------------------------------------------------------------------
39+
⚠ Which parts of the code is affected and which OAuth2 workflows are involved
40+
---------------------------------------------------------------------------- -->
41+
42+
43+
44+
## Added tests?
45+
<!-- ---------------------------------------------------------------------------
46+
⚠ Did you add tests that cover your changes?
47+
---------------------------------------------------------------------------- -->
48+
49+
50+
51+
## OAuth2 standard
52+
<!-- ---------------------------------------------------------------------------
53+
⚠ This section is important in order to review compliance with the standard(s).
54+
Please refer to the standard if your PR affects any functionality or is
55+
otherwise related to the standard(s) in any way
56+
---------------------------------------------------------------------------- -->
57+
58+
59+
60+
## Reproduction
61+
<!-- ---------------------------------------------------------------------------
62+
⚠ How can we reproduce your changes in an app? This is especially important
63+
when new features are added
64+
---------------------------------------------------------------------------- -->
65+

‎CONTRIBUTING.md

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Contributing to @node-oauth/oauth2-server
2+
3+
Thank you for your interest in this project and your aims to improving it.
4+
This guide will give you the most important info on how to contribute properly
5+
in order to get your pull requests accepted.
6+
7+
## Disclose security vulnerabilities
8+
9+
First things first:
10+
This project has strong security implications and we appreciate every help to
11+
improve security.
12+
13+
**However, please read our [security policy](./SECURITY.md), before taking
14+
actions.**
15+
16+
17+
18+
## Guiding principles
19+
20+
Before contributing to this project it is important to understand how this
21+
project and it's collaborators views itself regarding it's scope and purpose.
22+
23+
### OAuth2 standard compliance
24+
25+
This project aims full standard compliance. All improvements on functionality,
26+
as well as security implications, are done in a way that the standard remains
27+
as the highest reference of choice.
28+
29+
If you are not familiar with the OAuth2 standards, please consult at least the
30+
following documents:
31+
32+
- [RFC 6749 - The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749)
33+
- [RFC 8252 - OAuth 2.0 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252)
34+
35+
Extended readings:
36+
37+
- [RFC 6819 - OAuth 2.0 Threat Model and Security Considerations](https://datatracker.ietf.org/doc/html/rfc6819)
38+
- [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients](https://datatracker.ietf.org/doc/html/rfc7636)
39+
- [RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591)
40+
41+
### Framework agnostic
42+
43+
Design decisions and implementations are always done with keeping in mind, that
44+
there are multiple frameworks out there that use this project.
45+
46+
47+
48+
## Development
49+
50+
If you want to fix bugs or add new features, **please read this chapter and it's
51+
sections carefully!**
52+
53+
### No PR without issue
54+
55+
Please make sure your commitment will be appreciated by first opening an issue
56+
and discuss, whether this is a useful addition to the project.
57+
58+
### Work on a bug or a new feature
59+
60+
First, clone and install this project from source via
61+
62+
```bash
63+
$ git clone git@github.com:node-oauth/node-oauth2-server.git
64+
$ cd node-oauth2-server
65+
$ git checkout developmemt # important! do not work on master!
66+
$ npm install
67+
```
68+
69+
From here you can run several scripts for development purposes:
70+
71+
```bash
72+
$ npm run test # runs the tests once
73+
$ npm run test:coverage # runs the tests including coverage
74+
$ npm run docs # generates the API docs
75+
```
76+
77+
To work on a new feature or a fix please create a new branch:
78+
79+
```bash
80+
$ git checkout -b feature-xyz # or fix-xyz
81+
```
82+
83+
### Coding rules
84+
85+
- Unit-testing: all features or bug fixes must be tested by specs
86+
- Documentation: all public API methods must be documented
87+
88+
### Commit message convention
89+
90+
We use a commit convention, inspired by [angular commit message format](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format)
91+
with ticket number at the end of summary:
92+
93+
```
94+
<type>(<scope>): <short summary> #<issue nuber>
95+
```
96+
Summary in present tense. Not capitalized. No period at the end.
97+
The <type> and <summary> fields are mandatory, the (<scope>) and #<number> field is optional.
98+
99+
### Run the tests before committing
100+
101+
Please always make sure your code is passing linter and tests **before
102+
committing**. By doing so you help to make reviews much easier and don't pollute
103+
the history with commits, that are solely targeting lint fixes.
104+
105+
You can run the tests via
106+
107+
```bash
108+
$ npm run test
109+
```
110+
111+
or
112+
113+
```bash
114+
$ npm run test:coverage
115+
```
116+
117+
to see your coverage.
118+
119+
### Open a pull request (PR)
120+
121+
Once you have implemented your changes and tested them locally, please open
122+
a [pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
123+
124+
Note: sometimes a pull request (PR) is also referred to as merge request (MR).
125+
126+
#### Fundamental PR requirements
127+
128+
There are a few basic requirements for your pull request to become accepted:
129+
130+
- Make sure to open your pull request to target the `development` branch and not
131+
`master`
132+
- Make sure you are working on a branch, other than `development`; usually you
133+
can name the branch after the feature or fix you want to provide
134+
- Resolve any merge conflicts (usually by keeping your branch updated with
135+
`development`)
136+
- Have a clear description on what the PR does, including any steps necessary
137+
for testing, reviewing, reproduction etc.
138+
- Link to the existing issue
139+
- Added functions or changed functions need to get documented in compliance with
140+
JSDoc
141+
- Make sure all CI Tests are passing
142+
143+
Also make sure, to comply with the following list:
144+
145+
- Do not work on `development` directly
146+
- Do not implement multiple features in one pull request (this includes bumping
147+
versions of dependencies that are not related to the PR/issue)
148+
- Do not bump the release version (unless you are a maintainer)
149+
- Do not edit the Changelog as this will be done after your PR is merged
150+
- Do not introduce tight dependencies to a certain package that has not been
151+
approved during the discussion in the issue
152+
153+
#### Review process
154+
155+
Finally your PR needs to pass the review process:
156+
157+
- A certain amount of maintainers needs to review and accept your PR
158+
- Please **expect change requests**! They will occur and are intended to improve
159+
the overall code quality.
160+
- If your changes have been updated please re-assign the reviewer who asked for
161+
the changes
162+
- Once all reviewers have approved your PR it will be merged by one of the
163+
maintainers :tada:
164+
165+
#### After merge
166+
167+
Please delete your branch after merge.

‎README.md

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -40,12 +40,8 @@ This module has been rewritten using a promise-based approach, introducing chang
4040

4141
Please refer to our [3.0 migration guide](https://oauth2-server.readthedocs.io/en/latest/misc/migrating-v2-to-v3.html) for more information.
4242

43+
## Contributing to this project
4344

44-
## Tests
45-
46-
To run the test suite, install dependencies, then run `npm test`:
47-
48-
```bash
49-
npm install
50-
npm test
51-
```
45+
Please read our [contribution guide](./CONTRIBUTING.md) before taking actions.
46+
In any case, please open an issue before opening a pull request to find out,
47+
whether your intend to contribute will actually have a chance to be merged.

0 commit comments

Comments
 (0)