You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: .github/CONTRIBUTING.md
+2-228
Original file line number
Diff line number
Diff line change
@@ -16,235 +16,9 @@ The following is a set of guidelines for contributing to Rocket.Chat, which are
16
16
17
17
__Note:__ If there's a feature you'd like, there's a bug you'd like to fix, or you'd just like to get involved please raise an issue and start a conversation. We'll help as much as we can so you can get contributing - although we may not always be able to respond right away :)
18
18
19
-
## Setup
19
+
## Development Guidelines
20
20
21
-
Your development workstation needs to have at least 8GB RAM or more to be able to build the Rocket.Chat's source code.
22
-
23
-
Rocket.Chat runs on top of [Meteor](https://www.meteor.com/). To run it on development mode you need to [install Meteor](https://www.meteor.com/install) and clone/download the Rocket.Chat's code, then just open the code folder and run:
24
-
```shell
25
-
meteor npm install && meteor
26
-
```
27
-
It should build and run the application and database for you, now you can access the UI on (http://localhost:3000)
28
-
29
-
It's not necessary to install Nodejs or NPM, every time you need to use them you can run `meteor node` or `meteor npm`.
30
-
31
-
It's important to always run the NPM commands using `meteor npm` to ensure that you are installing the modules using the right Nodejs version.
32
-
33
-
## Coding
34
-
35
-
We provide a [.editorconfig](../.editorconfig) file that will help you to keep some standards in place.
36
-
37
-
### ECMAScript vs TypeScript
38
-
39
-
We are currently adopting TypeScript as the default language on our projects, the current codebase will be migrated incrementally from JavaScript to TypeScript.
40
-
41
-
While we still have a lot of JavaScript files you should not create new ones. As much as possible new code contributions should be in **TypeScript**.
42
-
43
-
### Blaze vs React
44
-
45
-
We are currently adopting React over Blaze as our UI engine, the current codebase is under migration and will continue. You will still find Blaze templates in our code. Code changes or contributions may need to be made in Blaze while we continue to evolve our components library.
46
-
47
-
[Fuselage](https://github.com/RocketChat/Rocket.Chat.Fuselage) is our component library based on React, check it out when contributing to the Rocket.Chat UI and feel free to contribute new components or fixes.
48
-
49
-
### Standards
50
-
51
-
Most of the coding standards are covered by ESLint configured at [.eslintrc](../.eslintrc), and most of them came from our own [ESLint Config Package](https://github.com/RocketChat/eslint-config-rocketchat).
52
-
53
-
Things not covered by `eslint`:
54
-
55
-
* Prefer longer/descriptive variable names, e.g. `error` vs `err`, unless dealing with common record properties already shortened, e.g. `rid` and `uid`
56
-
* Use return early pattern. [See more](https://blog.timoxley.com/post/47041269194/avoid-else-return-early)
57
-
* Prefer `Promise` over `callbacks`
58
-
* Prefer `await` over `then/catch`
59
-
* Don't create queries outside models, the query description should be inside the model class.
60
-
* Don't hardcode fields inside models. Same method can be used for different purposes, using different fields.
61
-
* Prefer create REST endpoints over Meteor methods
62
-
* Prefer call REST endpoints over Meteor methods when both are available
63
-
* v1 REST endpoints should follow the following pattern: `/api/v1/dashed-namespace.camelCaseAction`
64
-
* Prefer TypeScript over JavaScript. Check [ECMAScript vs TypeScript](#ecmascript-vs-typescript)
65
-
66
-
#### Blaze
67
-
* Import the HTML file from it's sibling JS/TS file
68
-
69
-
### Syntax check
70
-
71
-
Before submitting a PR you should get no errors on `eslint`.
72
-
73
-
To check your files run:
74
-
75
-
```shell
76
-
meteor npm run lint
77
-
```
78
-
79
-
## Tests
80
-
81
-
There are 2 types of tests we run on Rocket.Chat, **Unit** tests and **End to End** tests. The major difference is that End to End tests require a Rocket.Chat instance running to execute the API and UI checks.
82
-
83
-
### End to End Tests
84
-
85
-
First you need to run a Rocket.Chat server on **Test Mode** and on a **Empty Database**:
Unit tests are simpler to setup and run. They do not require a working Rocket.Chat instance.
103
-
```shell
104
-
meteor npm run testunit
105
-
```
106
-
107
-
It's possible to run on watch mode as well:
108
-
```shell
109
-
meteor npm run testunit-watch
110
-
```
111
-
112
-
<!-- ### Storybook -->
113
-
114
-
## Before Push your code
115
-
116
-
It's important to run the lint and tests before push your code or submit a Pull Request, otherwise your contribution may fail quickly on the CI. Reviewers are forced to demand fixes and the review of your contribution will be further delayed.
117
-
118
-
Rocket.Chat uses [husky](https://www.npmjs.com/package/husky) to run the **lint** and **unit tests** before proceed to the code push process, so you may notice a delay when pushing your code to your repository.
119
-
120
-
## Choosing a good PR title
121
-
122
-
It is very important to note that we use PR titles when creating our change log. Keep this in mind when you title your PR. Make sure the title makes sense to a person reading a releases' change log!
123
-
124
-
Keep your PR's title as short and concise as possible, use PR's description section, which you can find in the PR's template, to provide more details into the changelog.
125
-
126
-
Good titles require thinking from a user's point of view. Don't get technical and talk code or architecture. What is the actual user-facing feature or the bug fixed? For example:
127
-
128
-
```
129
-
[NEW] Allow search permissions and settings by name instead of only ID
130
-
```
131
-
132
-
Even it's being something new in the code the users already expect the filter to filter by what they see (translations), a better one would be:
133
-
134
-
```
135
-
[FIX] Permissions' search doesn't filter base on presented translation, only on internal ids
136
-
```
137
-
138
-
## Choosing the right PR tag
139
-
140
-
You can use several tags do describe your PR, i.e.: `[FIX]`, `[NEW]`, etc. You can use the descriptions below to better understand the meaning of each one, and decide which one you should use:
141
-
142
-
### `[NEW]`
143
-
144
-
#### When
145
-
- When adding a new feature that is important to the end user
146
-
147
-
#### How
148
-
149
-
Do not start repeating the section (`Add ...` or `New ...`)
150
-
Always describe what's being fixed, improved or added and not *how* it was fixed, improved or added.
151
-
152
-
Exemple of **bad** PR titles:
153
-
154
-
```
155
-
[NEW] Add ability to set tags in the Omnichannel room closing dialog
156
-
[NEW] Adds ability for Rocket.Chat Apps to create discussions
157
-
[NEW] Add MMS support to Voxtelesys
158
-
[NEW] Add Color variable to left sidebar
159
-
```
160
-
161
-
Exemple of **good** PR titles:
162
-
163
-
```
164
-
[NEW] Ability to set tags in the Omnichannel room closing dialog
165
-
[NEW] Ability for Rocket.Chat Apps to create discussions
166
-
[NEW] MMS support to Voxtelesys
167
-
[NEW] Color variable to left sidebar
168
-
```
169
-
170
-
### `[FIX]`
171
-
172
-
#### When
173
-
- When fixing something not working or behaving wrong from the end user perspective
174
-
175
-
#### How
176
-
177
-
Always describe what's being fixed and not *how* it was fixed.
178
-
179
-
Exemple of a **bad** PR title:
180
-
181
-
```
182
-
[FIX] Add Content-Type for public files with JWT
183
-
```
184
-
185
-
Exemple of a **good** PR title:
186
-
187
-
```
188
-
[FIX] Missing Content-Type header for public files with JWT
189
-
```
190
-
191
-
### `[IMPROVE]`
192
-
193
-
#### When
194
-
- When a change enhances a not buggy behavior. When in doubt if it's a Improve or Fix prefer to use as fix.
195
-
196
-
#### How
197
-
Always describe what's being improved and not *how* it was improved.
198
-
199
-
Exemple of **good** PR title:
200
-
201
-
```
202
-
[IMPROVE] Displays Nothing found on admin sidebar when search returns nothing
203
-
```
204
-
205
-
### `[BREAK]`
206
-
207
-
#### When
208
-
- When the changes affect a working feature
209
-
210
-
##### Back-End
211
-
- When the API contract (data structure and endpoints) are limited, expanded as required or removed
212
-
- When the business logic (permissions and roles) are limited, expanded (without migration) or removed
213
-
214
-
##### Front-End
215
-
- When the change limits (format, size, etc) or removes the ability of read or change the data (when the limitation was not caused by the back-end)
216
-
217
-
### Second tag e.g. `[NEW][ENTERPRISE]`
218
-
219
-
Use a second tag to group entries on the change log, we currently use it only for the Enterprise items but we are going to expand it's usage soon, please do not use it until we create a patter for it.
220
-
221
-
### Minor Changes
222
-
223
-
For those PRs that aren't important for the end user, we are working on a better pattern, but for now please use the same tags, use them without the brackets and in camel case:
224
-
225
-
```
226
-
Fix: Missing Content-Type header for public files with JWT
227
-
```
228
-
229
-
All those PRs will be grouped under the `Minor changes` section which is collapsed, so users can expand it to check for those minor things but they are not visible directly on changelog.
230
-
231
-
## Security Best Practices
232
-
233
-
- Never expose unnecessary data to the APIs' responses
234
-
- Always check for permissions or create new ones when you must expose sensitive data
235
-
- Never provide new APIs without rate limiters
236
-
- Always escape the user's input when rendering data
237
-
- Always limit the user's input size on server side
238
-
- Always execute the validations on the server side even when executing on the client side as well
239
-
240
-
## Performance Best Practices
241
-
242
-
- Prefer inform the fields you want, and only the necessary ones, when querying data from database over query the full documents
243
-
- Limit the number of returned records to a reasonable value
244
-
- Check if the query is using indexes, if it's not create new indexes
245
-
- Prefer queues over long executions
246
-
- Create new metrics to mesure things whenever possible
247
-
- Cache data and returns whenever possible
21
+
Check out our Handbook for the [Development Guidelines](https://handbook.rocket.chat/product/development/development-guidelines) on how to setup your enviroment, do code, test and push your code. There you find our patterns on how to compose your Pull Requests' titles to have your contribution accepted.
0 commit comments