Skip to content

Commit 40f4e64

Browse files
alvisalvis
committed
docs: add a guide for contribution
1 parent 7a889b3 commit 40f4e64

File tree

3 files changed

+294
-0
lines changed

3 files changed

+294
-0
lines changed

‎CODE_OF_CONDUCT.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, religion, or sexual identity
10+
and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behaviour that contributes to a positive environment for our
18+
community include:
19+
20+
- Demonstrating empathy and kindness toward other people
21+
- Being respectful of differing opinions, viewpoints, and experiences
22+
- Giving and gracefully accepting constructive feedback
23+
- Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
- Focusing on what is best not just for us as individuals, but for the
26+
overall community
27+
28+
Examples of unacceptable behaviour include:
29+
30+
- The use of sexualied language or imagery, and sexual attention or
31+
advances of any kind
32+
- Trolling, insulting or derogatory comments, and personal or political attacks
33+
- Public or private harassment
34+
- Publishing others' private information, such as a physical or email
35+
address, without their explicit permission
36+
- Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behaviour and will take appropriate and fair corrective action in
43+
response to any behaviour that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behaviour may be
62+
reported to the community leaders responsible for enforcement at alvis@hilbert.space.
63+
All complaints will be reviewed and investigated promptly and fairly.
64+
65+
All community leaders are obligated to respect the privacy and security of the
66+
reporter of any incident.
67+
68+
## Enforcement Guidelines
69+
70+
Community leaders will follow these Community Impact Guidelines in determining
71+
the consequences for any action they deem in violation of this Code of Conduct:
72+
73+
### 1. Correction
74+
75+
**Community Impact**: Use of inappropriate language or other behaviour deemed
76+
unprofessional or unwelcome in the community.
77+
78+
**Consequence**: A private, written warning from community leaders, providing
79+
clarity around the nature of the violation and an explanation of why the
80+
behaviour was inappropriate. A public apology may be requested.
81+
82+
### 2. Warning
83+
84+
**Community Impact**: A violation through a single incident or series
85+
of actions.
86+
87+
**Consequence**: A warning with consequences for continued behaviour. No
88+
interaction with the people involved, including unsolicited interaction with
89+
those enforcing the Code of Conduct, for a specified period of time. This
90+
includes avoiding interactions in community spaces as well as external channels
91+
like social media. Violating these terms may lead to a temporary or
92+
permanent ban.
93+
94+
### 3. Temporary Ban
95+
96+
**Community Impact**: A serious violation of community standards, including
97+
sustained inappropriate behaviour.
98+
99+
**Consequence**: A temporary ban from any sort of interaction or public
100+
communication with the community for a specified period of time. No public or
101+
private interaction with the people involved, including unsolicited interaction
102+
with those enforcing the Code of Conduct, is allowed during this period.
103+
Violating these terms may lead to a permanent ban.
104+
105+
### 4. Permanent Ban
106+
107+
**Community Impact**: Demonstrating a pattern of violation of community
108+
standards, including sustained inappropriate behaviour, harassment of an
109+
individual, or aggression toward or disparagement of classes of individuals.
110+
111+
**Consequence**: A permanent ban from any sort of public interaction within
112+
the community.
113+
114+
## Attribution
115+
116+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
117+
version 2.0, available at
118+
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
119+
120+
Community Impact Guidelines were inspired by [Mozilla's code of conduct
121+
enforcement ladder](https://github.com/mozilla/diversity).
122+
123+
[homepage]: https://www.contributor-covenant.org
124+
125+
For answers to common questions about this code of conduct, see the FAQ at
126+
https://www.contributor-covenant.org/faq. Translations are available at
127+
https://www.contributor-covenant.org/translations.

‎CONTRIBUTING.md

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Contributing to gatsby-source-notion
2+
3+
> Please note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md).
4+
> By participating in this project you agree to abide by its terms.
5+
6+
- [The Essential](#the-essential)
7+
- [Development](#development)
8+
- [Pull Request Submission](#pull-request-submission)
9+
- [Useful Commands](#useful-commands)
10+
11+
## The Essential
12+
13+
`gatsby-source-notion` relies on typescript and other tools for building and testing.
14+
Therefore, it's important that you have all the toolsets installed before making any change to the code.
15+
But setting up the code base is easy, just follow these steps:
16+
17+
1. Clone this repo
18+
2. Run `npm install`
19+
20+
---
21+
22+
## Development
23+
24+
We write code in [test-driven development (TDD)](https://en.wikipedia.org/wiki/test-driven_development) approach.
25+
26+
All tests are hosted under the `spec` folder, with the same structure as the `source` folder so that tests are easy to be located.
27+
In general, each source file should have its own test file.
28+
29+
### Code Standard
30+
31+
This project employs code standard rules exported from [presetter-preset](https://github.com/alvis/presetter/blob/master/packages/preset/templates/eslintrc.yaml),
32+
which mostly follow the recommended rules from
33+
34+
- [Eslint](https://eslint.org)
35+
- [TypeScript ESLint](https://typescript-eslint.io).
36+
- [Sonar](https://github.com/SonarSource/eslint-plugin-sonarjs)
37+
- [JSDoc](https://www.npmjs.com/package/eslint-plugin-jsdoc)
38+
39+
### Commit
40+
41+
To allow us to release in semantic versioning,
42+
we adopt the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard for commit messages.
43+
44+
A commit message should be structured as follows:
45+
46+
```
47+
<type>(<package>): <subject>
48+
<BLANK LINE>
49+
<body>
50+
```
51+
52+
Example
53+
54+
```
55+
feat: new awesome feature
56+
57+
BREAKING CHANGE: something will change the behaviour
58+
```
59+
60+
List of types:
61+
62+
- feat: A new feature
63+
- fix: A bug fix
64+
- docs: Documentation only changes
65+
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
66+
- refactor: A code change that neither fixes a bug nor adds a feature
67+
- perf: A code change that improves performance
68+
- test: Adding missing or correcting existing tests
69+
- build: Changes that affect the build system or external dependencies
70+
- ci: Changes to our CI configuration files
71+
- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
72+
- revert: Reverts a previous commit
73+
74+
---
75+
76+
## Pull Request Submission
77+
78+
This project follows [GitHub's standard forking model](https://guides.github.com/activities/forking/).
79+
Please fork the project in order to submit pull requests.
80+
81+
Obviously, PRs must be mergeable, rebasing first against the latest master.
82+
The number of commits will ideally be limited in number, unless extra commits can better show a progression of features.
83+
84+
**IMPORTANTLY**, make sure the following are achieved:
85+
86+
- commit messages must be worded clearly
87+
- the reason for any PR must be clearly stated by either linking to an issue or giving a full description of what it achieves.
88+
- all commits must follow the conventional commit standard
89+
- a test must shipped with any PR, if possible
90+
- 100% coverage must be maintained
91+
92+
---
93+
94+
## Useful Commands
95+
96+
The following contains some useful commands you would need during development.
97+
98+
### Running Test
99+
100+
#### Run all tests
101+
102+
```shell
103+
$ npm run test
104+
```
105+
106+
#### Run all tests when there is any file changes
107+
108+
```shell
109+
$ npm run watch
110+
```
111+
112+
#### Watch only some specific test files
113+
114+
```shell
115+
$ npm run watch -- spec/<file.spec.ts>
116+
```
117+
118+
#### Coverage
119+
120+
Run the coverage script to make sure the coverage is 100% before committing,
121+
then open `coverage/lcov-report/index.html` located in each individual package folder in your browser.
122+
123+
```shell
124+
# Either under individual package folder or the project root for all packages
125+
$ npm run coverage
126+
```
127+
128+
### Building
129+
130+
To transpile typescript to javascript, run the following:
131+
132+
```shell
133+
$ npm run build
134+
```
135+
136+
### Linting
137+
138+
To check the code standard and fix fixable issues automatically, run the following:
139+
140+
```shell
141+
$ npm run lint
142+
```
143+
144+
### Release
145+
146+
We follow semantic versioning and a release can be triggered by running either the following:
147+
148+
```shell
149+
# bump the version and release as canary
150+
$ npm run release --prerelease next
151+
152+
# release as a stable version
153+
$ npm run release
154+
```
155+
156+
**NOTE**:
157+
Upon releasing, automatically a versioning tag is issued and the change logs got updated.
158+
When the commit is pushed to the origin, the automated CI/CD system will then
159+
publish the package to npm automatically without any manual intervention.

‎README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -298,6 +298,14 @@ This source plugin is built on the official Notion API.
298298
If you are interested in using it as well, here is a [Postman collection](<(<(https://www.postman.com/notionhq/workspace/notion-s-public-api-workspace/overview)>)>) you can explore.
299299
Also follow the [official API documentation](https://developers.notion.com/reference/intro) to learn more about how to use it.
300300

301+
### Contributing
302+
303+
Any new ideas? or got a bug? We definitely would love to have your contribution!
304+
305+
Feel free to open a discussion, report a bug or ask for a new feature via [issues](https://github.com/alvis/gatsby-source-notion/issues).
306+
307+
Further, read the [contribution guide](https://github.com/alvis/gatsby-source-notion/blob/master/CONTRIBUTING.md) for the detail of the code structure and useful commands etc.
308+
301309
### License
302310

303311
Copyright © 2021, [Alvis Tang](https://github.com/alvis). Released under the [MIT License](LICENSE).

0 commit comments

Comments
 (0)