Skip to content

Commit 1a576c0

Browse files
seebeenseebeen
committed
docs: Added README and CONTRIBUTING
1 parent 88f6ce3 commit 1a576c0

File tree

2 files changed

+391
-6
lines changed

2 files changed

+391
-6
lines changed

‎CONTRIBUTING.md

+286
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
# Contributing to semantic-release
2+
3+
✨ Thanks for contributing to **semantic-release**! ✨
4+
5+
As a contributor, here are the guidelines we would like you to follow:
6+
7+
- [Code of conduct](#code-of-conduct)
8+
- [How can I contribute?](#how-can-i-contribute)
9+
- [Using the issue tracker](#using-the-issue-tracker)
10+
- [Submitting a Pull Request](#submitting-a-pull-request)
11+
- [Coding rules](#coding-rules)
12+
- [Working with the code](#working-with-the-code)
13+
14+
We also recommend that you read [How to Contribute to Open Source](https://opensource.guide/how-to-contribute).
15+
16+
## Code of conduct
17+
18+
Help us keep **semantic-release** open and inclusive. Please read and follow our [Code of conduct](CODE_OF_CONDUCT.md).
19+
20+
## How can I contribute?
21+
22+
### Improve documentation
23+
24+
As a **semantic-release** user, you are the perfect candidate to help us improve our documentation: typo corrections, clarifications, more examples, new [recipes](docs/recipes), etc. Take a look at the [documentation issues that need help](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Asemantic-release+archived%3Afalse+label%3A%22help+wanted%22+label%3Adocs+).
25+
26+
Please follow the [Documentation guidelines](#documentation).
27+
28+
### Give feedback on issues
29+
30+
Some issues are created without information requested in the [Bug report guideline](#bug-report).
31+
Help make them easier to resolve by adding any relevant information.
32+
33+
Issues with the [design label](https://github.com/issues?q=is%3Aopen+is%3Aissue+user%3Asemantic-release+archived%3Afalse+label%3Adesign) are meant to discuss the implementation of new features.
34+
Participating in the discussion is a good opportunity to get involved and influence the future direction of **semantic-release**.
35+
36+
### Fix bugs and implement features
37+
38+
Confirmed bugs and ready-to-implement features are marked with the [help wanted label](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Asemantic-release+archived%3Afalse+label%3A%22help+wanted%22).
39+
Post a comment on an issue to indicate you would like to work on it and to request help from the [@semantic-release/maintainers](https://github.com/orgs/semantic-release/teams/contributors) and the community.
40+
41+
## Using the issue tracker
42+
43+
The issue tracker is the channel for [bug reports](#bug-report), [features requests](#feature-request) and [submitting pull requests](#submitting-a-pull-request) only.
44+
Please use the [Support](docs/support/README.md) and [Get help](README.md#get-help) sections for support, troubleshooting and questions.
45+
46+
Before opening an issue or a Pull Request, please use the [GitHub issue search](https://github.com/issues?utf8=%E2%9C%93&q=user%3Asemantic-release) to make sure the bug or feature request hasn't been already reported or fixed.
47+
48+
### Bug report
49+
50+
A good bug report shouldn't leave others needing to chase you for more information.
51+
Please try to be as detailed as possible in your report and fill the information requested in the [bug report template](https://github.com/semantic-release/semantic-release/issues/new?template=01_bug_report.md).
52+
53+
### Feature request
54+
55+
Feature requests are welcome, but take a moment to find out whether your idea fits with the scope and aims of the project.
56+
It's up to you to make a strong case to convince the project's developers of the merits of this feature.
57+
Please provide as much detail and context as possible and fill the information requested in the [feature request template](https://github.com/semantic-release/semantic-release/issues/new?template=02_feature_request.md).
58+
59+
### New plugin request
60+
61+
[Plugins](docs/usage/plugins.md) are a great way to extend **semantic-release** capabilities, integrate with other systems and support new project type.
62+
Please provide as much detail and context as possible and fill the information requested in the [plugin suggestion template](https://github.com/semantic-release/semantic-release/issues/new?template=03_plugin_suggestion.md).
63+
64+
## Submitting a Pull Request
65+
66+
Good pull requests, whether patches, improvements, or new features, are a fantastic help.
67+
They should remain focused in scope and avoid containing unrelated commits.
68+
69+
**Please ask first** before embarking on any significant pull requests (e.g. implementing features, refactoring code), otherwise you risk spending a lot of time working on something that the project's maintainers might not want to merge into the project.
70+
71+
If you have never created a pull request before, welcome 🎉 😄.
72+
[Here is a great tutorial](https://opensource.guide/how-to-contribute/#opening-a-pull-request) on how to send one :)
73+
74+
Here is a summary of the steps to follow:
75+
76+
1. [Set up the workspace](#set-up-the-workspace)
77+
2. If you cloned a while ago, get the latest changes from upstream and update dependencies:
78+
79+
```bash
80+
$ git checkout master
81+
$ git pull upstream master
82+
$ rm -rf node_modules
83+
$ npm install
84+
```
85+
86+
3. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix:
87+
88+
```bash
89+
$ git checkout -b <topic-branch-name>
90+
```
91+
92+
4. Make your code changes, following the [Coding rules](#coding-rules)
93+
5. Push your topic branch up to your fork:
94+
95+
```bash
96+
$ git push origin <topic-branch-name>
97+
```
98+
99+
6. [Open a Pull Request](https://help.github.com/articles/creating-a-pull-request/#creating-the-pull-request) with a clear title and description.
100+
101+
**Tips**:
102+
103+
- For ambitious tasks, open a Pull Request as soon as possible with the `[WIP]` prefix in the title, in order to get feedback and help from the community.
104+
- [Allow semantic-release maintainers to make changes to your Pull Request branch](https://help.github.com/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork).
105+
This way, we can rebase it and make some minor changes if necessary.
106+
All changes we make will be done in new commit, and we'll ask for your approval before merging them.
107+
108+
## Coding rules
109+
110+
### Source code
111+
112+
To ensure consistency and quality throughout the source code, all code modifications must have:
113+
114+
- No [linting](#lint) errors
115+
- A [test](#tests) for every possible case introduced by your code change
116+
- **100%** test coverage
117+
- [Valid commit message(s)](#commit-message-guidelines)
118+
- Documentation for new features
119+
- Updated documentation for modified features
120+
121+
### Documentation
122+
123+
To ensure consistency and quality, all documentation modifications must:
124+
125+
- Refer to brand in [bold](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) with proper capitalization, i.e. **GitHub**, **semantic-release**, **npm**
126+
- Prefer [tables](https://help.github.com/articles/organizing-information-with-tables) over [lists](https://help.github.com/articles/basic-writing-and-formatting-syntax/#lists) when listing key values, i.e. List of options with their description
127+
- Use [links](https://help.github.com/articles/basic-writing-and-formatting-syntax/#links) when you are referring to:
128+
- a **semantic-release** concept described somewhere else in the documentation, i.e. How to [contribute](CONTRIBUTING.md)
129+
- a third-party product/brand/service, i.e. Integrate with [GitHub](https://github.com)
130+
- an external concept or feature, i.e. Create a [GitHub release](https://help.github.com/articles/creating-releases)
131+
- a package or module, i.e. The [`@semantic-release/github`](https://github.com/semantic-release/github) module
132+
- Use the [single backtick `code` quoting](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) for:
133+
- commands inside sentences, i.e. the `semantic-release` command
134+
- programming language keywords, i.e. `function`, `async`, `String`
135+
- packages or modules, i.e. The [`@semantic-release/github`](https://github.com/semantic-release/github) module
136+
- Use the [triple backtick `code` formatting](https://help.github.com/articles/creating-and-highlighting-code-blocks) for:
137+
- code examples
138+
- configuration examples
139+
- sequence of command lines
140+
141+
### Code signing
142+
143+
Since this project is related to WordPress, which is used by millions of sites, the risks of a [supply chain attack](https://en.wikipedia.org/wiki/Supply_chain_attack) are high. To mitigate this, we require all contributors to use [GPG](https://gnupg.org/) to sign all commits. If you would like to contribute to this project, you will need to [generate a GPG key](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/generating-a-new-gpg-key) and [add it to your GitHub account](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/adding-a-new-gpg-key-to-your-github-account). You will also need to [set your commit email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address) to the email address associated with your GPG key.
144+
145+
### Commit message guidelines
146+
147+
#### Atomic commits
148+
149+
If possible, make [atomic commits](https://en.wikipedia.org/wiki/Atomic_commit), which means:
150+
151+
- a commit should contain exactly one self-contained functional change
152+
- a functional change should be contained in exactly one commit
153+
- a commit should not create an inconsistent state (such as test errors, linting errors, partial fix, feature with documentation etc...)
154+
155+
A complex feature can be broken down into multiple commits as long as each one maintains a consistent state and consists of a self-contained change.
156+
157+
#### Commit message format
158+
159+
Each commit message consists of a **header**, a **body** and a **footer**.
160+
The header has a special format that includes a **type**, a **scope** and a **subject**:
161+
162+
```commit
163+
<type>(<scope>): <subject>
164+
<BLANK LINE>
165+
<body>
166+
<BLANK LINE>
167+
<footer>
168+
```
169+
170+
The **header** is mandatory and the **scope** of the header is optional.
171+
172+
The **footer** can contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages).
173+
174+
#### Revert
175+
176+
If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit.
177+
In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.
178+
179+
#### Type
180+
181+
The type must be one of the following:
182+
183+
| Type | Description |
184+
| ------------ | ----------------------------------------------------------------------------------------------------------- |
185+
| **build** | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |
186+
| **ci** | Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) |
187+
| **docs** | Documentation only changes |
188+
| **feat** | A new feature |
189+
| **fix** | A bug fix |
190+
| **perf** | A code change that improves performance |
191+
| **refactor** | A code change that neither fixes a bug nor adds a feature |
192+
| **style** | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
193+
| **test** | Adding missing tests or correcting existing tests |
194+
195+
#### Subject
196+
197+
The subject contains succinct description of the change:
198+
199+
- use the imperative, present tense: "change" not "changed" nor "changes"
200+
- don't capitalize first letter
201+
- no dot (.) at the end
202+
203+
#### Body
204+
205+
Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
206+
The body should include the motivation for the change and contrast this with previous behavior.
207+
208+
#### Footer
209+
210+
The footer should contain any information about **Breaking Changes** and is also the place to reference GitHub issues that this commit **Closes**.
211+
212+
**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines.
213+
The rest of the commit message is then used for this.
214+
215+
#### Examples
216+
217+
```commit
218+
fix(pencil): stop graphite breaking when too much pressure applied
219+
```
220+
221+
```commit
222+
feat(pencil): add 'graphiteWidth' option
223+
224+
Fix #42
225+
```
226+
227+
```commit
228+
perf(pencil): remove graphiteWidth option
229+
230+
BREAKING CHANGE: The graphiteWidth option has been removed.
231+
232+
The default graphite width of 10mm is always used for performance reasons.
233+
```
234+
235+
## Working with the code
236+
237+
### Set up the workspace
238+
239+
[Fork](https://guides.github.com/activities/forking/#fork) the project, [clone](https://guides.github.com/activities/forking/#clone) your fork, configure the remotes and install the dependencies:
240+
241+
```bash
242+
# Clone your fork of the repo into the current directory
243+
$ git clone https://github.com/semantic-release/<repo-name>
244+
# Navigate to the newly cloned directory
245+
$ cd <repo-name>
246+
# Assign the original repo to a remote called "upstream"
247+
$ git remote add upstream https://github.com/semantic-release/<repo-name>
248+
# Install the dependencies
249+
$ npm install
250+
```
251+
252+
### Lint
253+
254+
All the [semantic-release](https://github.com/semantic-release) repositories use [XO](https://github.com/sindresorhus/xo) for linting and [Prettier](https://prettier.io) for formatting.
255+
Prettier formatting will be automatically verified and fixed by XO.
256+
257+
Before pushing your code changes make sure there are no linting errors with `npm run lint`.
258+
259+
**Tips**:
260+
261+
- Most linting errors can be automatically fixed with `npm run lint -- --fix`.
262+
- Install the [XO plugin](https://github.com/sindresorhus/xo#editor-plugins) for your editor to see linting errors directly in your editor and automatically fix them on save.
263+
264+
### Tests
265+
266+
Running the integration test requires you to install [Docker](https://docs.docker.com/engine/installation) on your machine.
267+
268+
All the [semantic-release](https://github.com/semantic-release) repositories use [AVA](https://github.com/avajs/ava) for writing and running tests.
269+
270+
Before pushing your code changes make sure all **tests pass** and the **coverage is 100%**:
271+
272+
```bash
273+
$ npm run test
274+
```
275+
276+
**Tips:** During development you can:
277+
278+
- run only a subset of test files with `ava <glob>`, for example `ava test/mytestfile.test.js`
279+
- run in watch mode with `ava -w` to automatically run a test file when you modify it
280+
- run only the test you are working on by adding [`.only` to the test definition](https://github.com/avajs/ava#running-specific-tests)
281+
282+
### Commits
283+
284+
All the [semantic-release](https://github.com/semantic-release) repositories use [Commitizen](https://github.com/commitizen/cz-cli) to help you create [valid commit messages](#commit-message-guidelines).
285+
286+
After staging your changes with `git add`, run `npm run cm` to start the interactive commit message CLI.

0 commit comments

Comments
 (0)