CONTRIBUTING.md 8.6 KB
Newer Older
1
# Contribute to Strapi
2

3
Strapi is an open-source project administered by [the Strapi team](https://strapi.io/company). We appreciate your interest and efforts to contribute to Strapi.
4

5
All efforts to contribute are highly appreciated, we recommend you talk to a maintainer prior to spending a lot of time making a pull request that may not align with the project roadmap.
6

7
## Open Development & Community Driven
S
soupette 已提交
8

A
Alexandre Bodin 已提交
9
Strapi is an open-source project. See the [LICENSE](https://github.com/strapi/strapi/blob/master/LICENSE) file for licensing information. All the work done is available on GitHub.
10

C
cyril lopez 已提交
11 12
The core team and the contributors send pull requests which go through the same validation process.

13 14 15
## Feature Requests

Feature Requests by the community are highly encouraged. Please feel free to submit a [feature request](https://portal.productboard.com/strapi) or to upvote 👍 [an existing feature request](https://portal.productboard.com/strapi) in the ProductBoard.
C
cyril lopez 已提交
16

17 18 19 20 21 22 23 24
## RFCs

Some important changes in Strapi require some thoughts to be put into the design phase before starting working on a PR.

The RFC (Request For Comments) process will help us create consensus among the core team and include as much feedback as possible from the community, for these upcoming changes.

Before contributing, you will probably have to create a RFC on this [strapi/rfcs](https://github.com/strapi/rfcs) repo.

S
soupette 已提交
25
## Code of Conduct
C
cyril lopez 已提交
26

27
This project and everyone participating in it are governed by the [Strapi Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please read the [full text](CODE_OF_CONDUCT.md) so that you can read which actions may or may not be tolerated.
C
cyril lopez 已提交
28

29 30 31 32 33 34 35 36 37 38
## Contributor License Agreement (CLA)

### Individual

In order to accept your pull request, we need you to submit a CLA. You only need to do this once. If you are submitting a pull request for the first time, you can complete your CLA [here](https://cla.strapi.io/strapi/strapi) or just submit a Pull Request and our CLA Bot will ask you to sign the CLA before merging your Pull Request.

### Company

If you are making contributions to our repositories on behalf of your company, then we will need a Corporate Contributor License Agreement (CLA) signed. In order to do that, please contact us at [contributions@strapi.io](mailto:contributions@strapi.io).

39 40
## Documentation

41
Pull requests relating to fixing documentation for the latest release should be directed towards the [documentation repo](https://github.com/strapi/documentation). Please see the documentation [contributing guide](https://github.com/strapi/documentation/blob/main/CONTRIBUTING.md) for more information on how to make the documentation pull request.
42

S
soupette 已提交
43
## Bugs
C
cyril lopez 已提交
44

45
We are using [GitHub Issues](https://github.com/strapi/strapi/issues) to manage our public bugs. We keep a close eye on this so before filing a new issue, try to make sure the problem does not already exist.
C
cyril lopez 已提交
46

S
soupette 已提交
47
---
N
Nick Verwymeren 已提交
48

S
soupette 已提交
49
## Before Submitting a Pull Request
C
cyril lopez 已提交
50

S
soupette 已提交
51
The core team will review your pull request and will either merge it, request changes to it, or close it.
C
cyril lopez 已提交
52

S
soupette 已提交
53
**Before submitting your pull request** make sure the following requirements are fulfilled:
C
cyril lopez 已提交
54

S
soupette 已提交
55 56
- Fork the repository and create your branch from `master`.
- Run `yarn setup` in the repository root.
57 58
- If you’ve fixed a bug or added code that should be tested, add the tests and then link the corresponding issue in either your commit or your PR!
- Ensure the test suites are passing:
S
soupette 已提交
59 60 61
  - `yarn test:unit`
  - `yarn test:front`
- Make sure your code lints (`yarn lint`).
J
Jim Laurie 已提交
62

S
soupette 已提交
63
## Contribution Prerequisites
J
Jim Laurie 已提交
64

65
- You have [Node](https://nodejs.org/en/) at >= v10 and <= v14 and [Yarn](https://yarnpkg.com/en/) at v1.2.0+.
S
soupette 已提交
66
- You are familiar with Git.
67

S
soupette 已提交
68
## Development Workflow
C
cyril lopez 已提交
69

70 71
_For users running on Apple Silicon M1, you may encounter errors thrown by `sharp`. You may need to re-install `libvps` or to build `sharp` manually following [this issue comment](https://github.com/lovell/sharp/issues/2460#issuecomment-751491241) in order to start the project._

72 73
To facilitate the contribution, we have drastically reduced the amount of commands necessary to install the entire development environment.

74
First of all, you need to check if you're using the [required versions of Node.js and npm](https://strapi.io/documentation/developer-docs/latest/setup-deployment-guides/deployment.html#recommended-requirements).
C
cyril lopez 已提交
75

S
soupette 已提交
76
Then, please follow the instructions below:
C
cyril lopez 已提交
77

78
#### 1. Fork the [repository](https://github.com/strapi/strapi)
S
soupette 已提交
79 80 81

[Go to the repository](https://github.com/strapi/strapi) and fork it to your own GitHub account.

82
#### 2. Clone from your repository
A
Aurelsicoko 已提交
83 84

```bash
S
soupette 已提交
85
git clone git@github.com:YOUR_USERNAME/strapi.git
A
Aurelsicoko 已提交
86 87
```

88
#### 3. Install the dependencies
A
Aurelsicoko 已提交
89

S
soupette 已提交
90
Go to the root of the repository.
A
Aurelsicoko 已提交
91 92

```bash
S
soupette 已提交
93
cd strapi && yarn setup
A
Aurelsicoko 已提交
94 95
```

96
#### 4. Start the example application
A
Aurelsicoko 已提交
97

98 99 100 101 102 103 104
To start a test example application to test your changes quickly and also for the next step.

```bash
cd strapi/examples/getstarted && yarn develop
```

Read the `getstarted` application README [here](./examples/getstarted/README.md) for more details.
A
Aurelsicoko 已提交
105

106
#### 5. Running the administration panel in development mode
A
Aurelsicoko 已提交
107

108
**Start the administration panel server for development**
S
soupette 已提交
109

A
Aurelsicoko 已提交
110
```bash
S
soupette 已提交
111 112
cd strapi/packages/strapi-admin
yarn develop
A
Aurelsicoko 已提交
113 114
```

J
Jim LAURIE 已提交
115
The administration panel will be available at http://localhost:4000/admin
A
Aurelsicoko 已提交
116 117 118

**Awesome! You are now able to contribute to Strapi.**

119
#### 6. Available commands
S
soupette 已提交
120 121 122 123 124 125 126 127 128 129 130 131 132

- `yarn watch` starts yarn watch in all packages.
- `yarn build` builds the `strapi-helper-plugin` (use this command when you develop in the administration panel).
- `yarn setup` installs the dependencies.
- `yarn lint` lints the codebase.
- `yarn test:clean` removes the coverage.
- `yarn test:front` runs the front-end related tests.
- `yarn test:front:watch` runs an interactive test watcher for the front-end.
- `yarn test:snyk` checks the dependencies vulnerabilities.
- `yarn test:unit` runs the back-end unit tests.
- `yarn test:e2e` runs an end-to-end test suite.
- `yarn test:generate-app` generates a test application.
- `yarn test:start-app` starts the test application.
A
Aurelsicoko 已提交
133 134

---
C
cyril lopez 已提交
135

A
Alexandre Bodin 已提交
136 137
## Running the tests

S
soupette 已提交
138
**Changing the database:**
A
Alexandre Bodin 已提交
139

140 141
You can run the test suites using different databases:

A
Alexandre Bodin 已提交
142
```bash
A
Alexandre Bodin 已提交
143 144 145 146
$ node test/e2e.js --db=sqlite
$ node test/e2e.js --db=mongo
$ node test/e2e.js --db=postgres
$ node test/e2e.js --db=mysql
A
Alexandre Bodin 已提交
147 148
```

S
soupette 已提交
149
---
A
Alexandre Bodin 已提交
150

151
## Miscellaneous
A
Alexandre Bodin 已提交
152

S
soupette 已提交
153
### Repository Organization
A
Alexandre Bodin 已提交
154

155
We chose to use a monorepo design that exploits [Yarn Workspaces](https://yarnpkg.com/en/docs/workspaces) in the way [React](https://github.com/facebook/react/tree/master/packages) or [Babel](https://github.com/babel/babel/tree/master/packages) does. This allows the community to easily maintain the whole ecosystem, keep it up-to-date and consistent.
A
Alexandre Bodin 已提交
156

157
We do our best to keep the master branch as clean as possible, with tests passing at all times. However, it may happen that the master branch moves faster than the release cycle. Therefore check the [releases on npm](https://www.npmjs.com/package/strapi) so that you're always up-to-date with the latest stable version.
A
Alexandre Bodin 已提交
158

S
soupette 已提交
159
### Reporting an issue
160

161
Before submitting an issue you need to make sure:
S
soupette 已提交
162

163 164 165
- You are experiencing a concrete technical issue with Strapi.
- You have already searched for related [issues](https://github.com/strapi/strapi/issues), and found none open (if you found a related _closed_ issue, please link to it from your post).
- You are not asking a question about how to use Strapi or about whether or not Strapi has a certain feature. For general help using Strapi, you may:
166
  - Refer to [the official Strapi documentation](https://strapi.io).
167
  - Ask a member of the community in the [Strapi Slack Community](https://slack.strapi.io/).
168
  - Ask a question on [our community forum](https://forum.strapi.io).
169
- Your issue title is concise, on-topic and polite.
170
- You can and do provide steps to reproduce your issue.
171 172
- You have tried all the following (if relevant) and your issue remains:
  - Make sure you have the right application started.
173
  - Make sure the [issue template](.github/ISSUE_TEMPLATE) is respected.
J
typo  
jundi14 已提交
174
  - Make sure your issue body is readable and [well formatted](https://guides.github.com/features/mastering-markdown).
175 176
  - Make sure you've killed the Strapi server with CTRL+C and started it again.
  - Make sure the application you are using to reproduce the issue has a clean `node_modules` directory, meaning:
S
soupette 已提交
177 178 179
    - no dependencies are linked (e.g. you haven't run `npm link`)
    - that you haven't made any inline changes to files in the `node_modules` folder
    - that you don't have any weird global dependency loops. The easiest way to double-check any of the above, if you aren't sure, is to run: `$ rm -rf node_modules && npm cache clear && npm install`.