CONTRIBUTING.md 7.0 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

F
Felix Fichte 已提交
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) if you are interested in helping us or [drop us an email](mailto:hi@strapi.io) if you are interested in working with us.
10

11 12 13 14 15
## Code of Conduct

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 report unacceptable behavior to [hi@strapi.io](mailto:hi@strapi.io).

## Open Development & Community Driven
C
cyril lopez 已提交
16 17 18
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 已提交
19
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 已提交
20

21
## Repository Organization
C
cyril lopez 已提交
22 23
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.

F
Farooq Abdul Rehman 已提交
24
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).
C
cyril lopez 已提交
25

F
Farooq Abdul Rehman 已提交
26
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).
C
cyril lopez 已提交
27

F
Farooq Abdul Rehman 已提交
28
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.
C
cyril lopez 已提交
29

30
***
C
cyril lopez 已提交
31

32
## Setup Development Environment
J
Jim LAURIE 已提交
33
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/installation.html#requirements)
C
cyril lopez 已提交
34

A
Aurelsicoko 已提交
35
Then, please follow the instructions below:
C
cyril lopez 已提交
36

A
Aurélien GEORGET 已提交
37
#### 1. ▪️ Fork the repository
C
cyril lopez 已提交
38

A
Aurelsicoko 已提交
39
[Go to the repository](https://github.com/strapi/strapi) and fork it to your own GitHub account.
C
cyril lopez 已提交
40

41
#### 2. 💿 Clone from your repository
J
Jim Laurie 已提交
42

A
Aurelsicoko 已提交
43
```bash
44
git clone git@github.com:YOUR_USERNAME/strapi.git
A
Aurelsicoko 已提交
45
```
J
Jim Laurie 已提交
46

A
Aurelsicoko 已提交
47
#### 3. ⏳ Installation
48

A
Aurelsicoko 已提交
49 50 51 52
Go to the root of the repository.
```bash
cd strapi
```
C
cyril lopez 已提交
53

A
Aurélien GEORGET 已提交
54
**Two setup are available... with or without the front-end builds.**
C
cyril lopez 已提交
55

F
Farooq Abdul Rehman 已提交
56
Without the front-end builds, you won't be able to access the administration panel via http://localhost:1337/admin. You'll have to run the administration separately and access it through http://localhost:4000/admin.
C
cyril lopez 已提交
57

A
Aurelsicoko 已提交
58 59
<br>

A
Aurélien GEORGET 已提交
60
Without the front-end builds (recommended)
A
Aurelsicoko 已提交
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105
```bash
npm run setup
```
or with the front-end builds
```bash
npm run setup:build
```

> ⚠️  If the installation failed, please remove the global packages related to Strapi. The command `npm ls strapi` will help you to find where your packages are installed globally.

#### 4. 🏗 Create a new project

You can open a new terminal window and go into any folder you want for the next steps.
```bash
cd /.../workspace/
```

The command to generate a project is the same, except you have to add the `--dev` argument at the end of line.
```bash
strapi new my-project --dev
```

#### 5. 🚀 Start the project

First, you have to start the server.
```bash
cd ./my-project
strapi start
```

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.

Then, you have to start the Webpack server to build and run the administration.
```bash
cd ./my-project/admin
npm run start
```

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

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

---
C
cyril lopez 已提交
106

107
## Plugin Development Setup
C
cyril lopez 已提交
108

A
Aurelsicoko 已提交
109
To create a new plugin, you'll have to run the following commands:
C
cyril lopez 已提交
110

A
Aurélien GEORGET 已提交
111
#### 1. 🏗 Generate a new plugin
C
cyril lopez 已提交
112

A
Aurelsicoko 已提交
113 114 115 116 117
```bash
cd ./my-project
strapi generate:plugin my-plugin
```

A
Aurélien GEORGET 已提交
118
#### 2. ✅ Verify the symlink
A
Aurelsicoko 已提交
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133

Make you that the `strapi-helper-plugin` is linked to your project.

Please run this command in the repository folder where Strapi is cloned:
```bash
cd /repository/strapi/packages/strapi-helper-plugin
npm link
```

Link the `strapi-helper-plugin` node_modules in the plugin folder:
```bash
cd ./my-project/plugins/my-plugin
npm link strapi-helper-plugin
```

A
Aurélien GEORGET 已提交
134
#### 3. 🚀 Start the project
A
Aurelsicoko 已提交
135 136 137 138 139 140 141 142 143

```bash
cd ./my-project/admin
npm run start
```

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

---
C
cyril lopez 已提交
144

145 146 147 148 149
## Reporting an issue

Before reporting an issue you need to make sure:
- 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 159 160 161
- 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:
    * 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`.