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

A
Aurélien GEORGET 已提交
3
First off, thanks for taking the time to contribute! 🎉👍
4

5 6 7
The following is a set of guidelines for contributing to Strapi and its packages.

Strapi is an open-source project administered by [the Strapi team](https://strapi.io/company).
8

S
soupette 已提交
9
Before contributing, ensure that your effort is aligned with the project's roadmap by talking to the maintainers, especially if you are going to spend a lot of time on it. Feel free to [join us on Slack](http://slack.strapi.io) or [drop us an email](mailto:hi@strapi.io) if you are interested in helping us or working with us.
10

11
## Open Development & Community Driven
S
soupette 已提交
12

C
cyril lopez 已提交
13 14 15
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.
The core team and the contributors send pull requests which go through the same validation process.

M
mnlbox 已提交
16
Every user can send a feature request using the [issues](https://github.com/strapi/strapi/issues/new?template=FEATURE_REQUEST.md) on GitHub. Feel free to upvote 👍 [existing feature request](https://portal.productboard.com/strapi)
C
cyril lopez 已提交
17

S
soupette 已提交
18
## Code of Conduct
C
cyril lopez 已提交
19

S
soupette 已提交
20
This project and everyone participating in it is 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 understand what actions will and will not be tolerated.
C
cyril lopez 已提交
21

S
soupette 已提交
22
## Bugs
C
cyril lopez 已提交
23

S
soupette 已提交
24
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 filling a new issue, try to make sure the problem does not already exist.
C
cyril lopez 已提交
25

S
soupette 已提交
26
## Get in Touch
C
cyril lopez 已提交
27

S
soupette 已提交
28 29
- [Slack](https://slack.strapi.io/)
- [Spectrum](https://spectrum.chat/strapi?tab=posts)
C
cyril lopez 已提交
30

S
soupette 已提交
31
---
N
Nick Verwymeren 已提交
32

S
soupette 已提交
33
## Before Submitting a Pull Request
C
cyril lopez 已提交
34

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

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

S
soupette 已提交
39 40 41 42 43 44 45
- Fork the repository and create your branch from `master`.
- Run `yarn setup` in the repository root.
- If you’ve fixed a bug or added code that should be tested, add tests and link the corresponding issue in either your commit or your PR!
- Ensure the test suite passes:
  - `yarn test:unit`
  - `yarn test:front`
- Make sure your code lints (`yarn lint`).
J
Jim Laurie 已提交
46

S
soupette 已提交
47
## Contribution Prerequisites
J
Jim Laurie 已提交
48

S
soupette 已提交
49
- You have [Node](https://nodejs.org/en/) at v10.0.0 only and [Yarn](https://yarnpkg.com/en/) at v1.2.0+.
S
soupette 已提交
50
- You are familiar with Git.
51

S
soupette 已提交
52
## Development Workflow
C
cyril lopez 已提交
53

S
soupette 已提交
54
To facilitate the contribution, we drastically reduce the amount of commands necessary to install the entire development environment. First of all, you need to check if you're using the [required versions of Node.js and npm](https://strapi.io/documentation/3.x.x/getting-started/install-requirements.html)
C
cyril lopez 已提交
55

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

S
soupette 已提交
58 59 60 61 62
#### 1. ▪ Fork the [repository](https://github.com/strapi/strapi)

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

#### 2. 💿 Clone from your repository
A
Aurelsicoko 已提交
63 64

```bash
S
soupette 已提交
65
git clone git@github.com:YOUR_USERNAME/strapi.git
A
Aurelsicoko 已提交
66 67
```

S
soupette 已提交
68
#### 3. ⏳ Install the dependencies
A
Aurelsicoko 已提交
69

S
soupette 已提交
70
Go to the root of the repository.
A
Aurelsicoko 已提交
71 72

```bash
S
soupette 已提交
73
cd strapi && yarn setup
A
Aurelsicoko 已提交
74 75
```

S
soupette 已提交
76
#### 4. 🚀 Start the example application
A
Aurelsicoko 已提交
77

S
soupette 已提交
78
**Go to the getstarted application**
A
Aurelsicoko 已提交
79 80

```bash
S
soupette 已提交
81 82
cd strapi/examples/getstarted
yarn develop
A
Aurelsicoko 已提交
83 84 85 86 87 88
```

The server (API) is available at http://localhost:1337

> ⚠️  If you've followed the recommended setup, you should not be able to reach the administration panel at http://localhost:1337/admin.

S
soupette 已提交
89 90
**Start the administration panel server**

A
Aurelsicoko 已提交
91
```bash
S
soupette 已提交
92 93
cd strapi/packages/strapi-admin
yarn develop
A
Aurelsicoko 已提交
94 95 96 97 98 99
```

The administration panel is available at http://localhost:4000/admin

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

S
soupette 已提交
100 101 102 103 104 105 106 107 108 109 110 111 112 113
#### 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 已提交
114 115

---
C
cyril lopez 已提交
116

A
Alexandre Bodin 已提交
117 118 119 120
## Running the tests

You can run three different kind of tests:

S
soupette 已提交
121
**Changing the database:**
A
Alexandre Bodin 已提交
122 123

```bash
S
soupette 已提交
124 125 126 127
$ node test/e2e.js sqlite
$ node test/e2e.js mongo
$ node test/e2e.js postgres
$ node test/e2e.js mysql
A
Alexandre Bodin 已提交
128 129
```

S
soupette 已提交
130
---
A
Alexandre Bodin 已提交
131

S
soupette 已提交
132
## Additional informations
A
Alexandre Bodin 已提交
133

S
soupette 已提交
134
### Repository Organization
A
Alexandre Bodin 已提交
135

S
soupette 已提交
136
We made the choice to use a monorepo design such as [React](https://github.com/facebook/react/tree/master/packages), [Babel](https://github.com/babel/babel/tree/master/packages), [Meteor](https://github.com/meteor/meteor/tree/devel/packages) or [Ember](https://github.com/emberjs/ember.js/tree/master/packages) do. It allows the community to easily maintain the whole ecosystem up-to-date and consistent.
A
Alexandre Bodin 已提交
137

S
soupette 已提交
138
The Babel team wrote an excellent short post about [the pros and cons of the monorepo design](https://github.com/babel/babel/blob/master/doc/design/monorepo.md).
A
Alexandre Bodin 已提交
139

S
soupette 已提交
140
We will do our best to keep the master branch as clean as possible, with tests passing all the times. However, it can happen that the master branch moves faster than the release cycle. To ensure you have the latest stable version, please refer to the [release on npm](https://www.npmjs.com/package/strapi).
A
Alexandre Bodin 已提交
141

S
soupette 已提交
142
If you send a pull request, please do it against the `master` branch. We are developing upcoming versions separately to ensure non-breaking changes from master to the latest stable major version.
A
Alexandre Bodin 已提交
143

S
soupette 已提交
144
### Reporting an issue
145 146

Before reporting an issue you need to make sure:
S
soupette 已提交
147

148 149
- You are experiencing a concrete technical issue with Strapi (ideas and feature proposals should happen [on Slack](http://slack.strapi.io)).
- 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, please refer to [the official Strapi documentation](http://strapi.io). For additional help, ask a question on [StackOverflow](http://stackoverflow.com/questions/tagged/strapi).
150
- 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 in your post).
151 152 153 154 155 156 157 158
- Your issue title is concise, on-topic and polite.
- You can provide steps to reproduce this issue that others can follow.
- You have tried all the following (if relevant) and your issue remains:
  - Make sure you have the right application started.
  - Make sure you've killed the Strapi server with CTRL+C and started it again.
  - Make sure you closed any open browser tabs pointed at `localhost` before starting Strapi.
  - Make sure you do not have any other Strapi applications running in other terminal windows.
  - Make sure the application you are using to reproduce the issue has a clean `node_modules` directory, meaning:
S
soupette 已提交
159 160 161
    - 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`.