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

D
davidkartuzinski 宸叉彁浜
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

D
davidkartuzinski 宸叉彁浜
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

C
cyril lopez 宸叉彁浜
9
Strapi is open-source under the [MIT license](https://github.com/strapi/strapi/blob/master/LICENSE.md). All the work done is available on GitHub.
D
davidkartuzinski 宸叉彁浜
10

C
cyril lopez 宸叉彁浜
11 12
The core team and the contributors send pull requests which go through the same validation process.

D
davidkartuzinski 宸叉彁浜
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

D
davidkartuzinski 宸叉彁浜
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

S
soupette 宸叉彁浜
29
## Bugs
C
cyril lopez 宸叉彁浜
30

D
davidkartuzinski 宸叉彁浜
31
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 宸叉彁浜
32

S
soupette 宸叉彁浜
33
---
N
Nick Verwymeren 宸叉彁浜
34

S
soupette 宸叉彁浜
35
## Before Submitting a Pull Request
C
cyril lopez 宸叉彁浜
36

S
soupette 宸叉彁浜
37
The core team will review your pull request and will either merge it, request changes to it, or close it.
C
cyril lopez 宸叉彁浜
38

S
soupette 宸叉彁浜
39
**Before submitting your pull request** make sure the following requirements are fulfilled:
C
cyril lopez 宸叉彁浜
40

S
soupette 宸叉彁浜
41 42
- Fork the repository and create your branch from `master`.
- Run `yarn setup` in the repository root.
D
davidkartuzinski 宸叉彁浜
43 44
- If you鈥檝e 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 宸叉彁浜
45 46 47
  - `yarn test:unit`
  - `yarn test:front`
- Make sure your code lints (`yarn lint`).
J
Jim Laurie 宸叉彁浜
48

S
soupette 宸叉彁浜
49
## Contribution Prerequisites
J
Jim Laurie 宸叉彁浜
50

A
Alexandre BODIN 宸叉彁浜
51
- You have [Node](https://nodejs.org/en/) at v10.x.x only and [Yarn](https://yarnpkg.com/en/) at v1.2.0+.
S
soupette 宸叉彁浜
52
- You are familiar with Git.
53

S
soupette 宸叉彁浜
54
## Development Workflow
C
cyril lopez 宸叉彁浜
55

D
davidkartuzinski 宸叉彁浜
56 57
To facilitate the contribution, we have drastically reduced the amount of commands necessary to install the entire development environment.

J
Jim LAURIE 宸叉彁浜
58
First of all, you need to check if you're using the [required versions of Node.js and npm](https://strapi.io/documentation/3.0.0-beta.x/getting-started/install-requirements.html)
C
cyril lopez 宸叉彁浜
59

S
soupette 宸叉彁浜
60
Then, please follow the instructions below:
C
cyril lopez 宸叉彁浜
61

62
#### 1. Fork the [repository](https://github.com/strapi/strapi)
S
soupette 宸叉彁浜
63 64 65

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

66
#### 2. Clone from your repository
A
Aurelsicoko 宸叉彁浜
67 68

```bash
S
soupette 宸叉彁浜
69
git clone git@github.com:YOUR_USERNAME/strapi.git
A
Aurelsicoko 宸叉彁浜
70 71
```

72
#### 3. Install the dependencies
A
Aurelsicoko 宸叉彁浜
73

S
soupette 宸叉彁浜
74
Go to the root of the repository.
A
Aurelsicoko 宸叉彁浜
75 76

```bash
S
soupette 宸叉彁浜
77
cd strapi && yarn setup
A
Aurelsicoko 宸叉彁浜
78 79
```

80
#### 4. Start the example application
A
Aurelsicoko 宸叉彁浜
81

82
Read the `getstarted` application README [here](./examples/getstarted/README.md).
A
Aurelsicoko 宸叉彁浜
83

84
#### 5. Running the administration panel in development mode
A
Aurelsicoko 宸叉彁浜
85

86
**Start the administration panel server for development**
S
soupette 宸叉彁浜
87

A
Aurelsicoko 宸叉彁浜
88
```bash
S
soupette 宸叉彁浜
89 90
cd strapi/packages/strapi-admin
yarn develop
A
Aurelsicoko 宸叉彁浜
91 92
```

J
Jim LAURIE 宸叉彁浜
93
The administration panel will be available at http://localhost:4000/admin
A
Aurelsicoko 宸叉彁浜
94 95 96

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

S
soupette 宸叉彁浜
97 98 99 100 101 102 103 104 105 106 107 108 109 110
#### 5. Available commands

- `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 宸叉彁浜
111 112

---
C
cyril lopez 宸叉彁浜
113

A
Alexandre Bodin 宸叉彁浜
114 115
## Running the tests

S
soupette 宸叉彁浜
116
**Changing the database:**
A
Alexandre Bodin 宸叉彁浜
117

D
davidkartuzinski 宸叉彁浜
118 119
You can run the test suites using different databases:

A
Alexandre Bodin 宸叉彁浜
120
```bash
A
Alexandre Bodin 宸叉彁浜
121 122 123 124
$ 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 宸叉彁浜
125 126
```

S
soupette 宸叉彁浜
127
---
A
Alexandre Bodin 宸叉彁浜
128

D
davidkartuzinski 宸叉彁浜
129
## Miscellaneous
A
Alexandre Bodin 宸叉彁浜
130

S
soupette 宸叉彁浜
131
### Repository Organization
A
Alexandre Bodin 宸叉彁浜
132

D
davidkartuzinski 宸叉彁浜
133
We chose to 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 宸叉彁浜
134

D
davidkartuzinski 宸叉彁浜
135
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 宸叉彁浜
136

S
soupette 宸叉彁浜
137
### Reporting an issue
138

D
davidkartuzinski 宸叉彁浜
139
Before submitting an issue you need to make sure:
S
soupette 宸叉彁浜
140

D
davidkartuzinski 宸叉彁浜
141 142 143 144 145
- 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:
  - Refer to [the official Strapi documentation](http://strapi.io).
  - Ask a member of the community in the [Strapi Slack Community](https://slack.strapi.io/).
146
  - Ask a question on [Github Discussions](https://github.com/strapi/strapi/discussions).
147
- Your issue title is concise, on-topic and polite.
D
davidkartuzinski 宸叉彁浜
148
- You can and do provide steps to reproduce your issue.
149 150
- You have tried all the following (if relevant) and your issue remains:
  - Make sure you have the right application started.
151
  - Make sure the [issue template](.github/ISSUE_TEMPLATE) is respected.
J
typo  
jundi14 宸叉彁浜
152
  - Make sure your issue body is readable and [well formatted](https://guides.github.com/features/mastering-markdown).
153 154
  - 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 宸叉彁浜
155 156 157
    - 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`.