CONTRIBUTING.md 8.69 KB
Newer Older
Chocobozzz's avatar
Chocobozzz committed
1
2
# Welcome to the contributing guide for PeerTube

Rigel Kent's avatar
Rigel Kent committed
3
Interested in contributing? Awesome!
Chocobozzz's avatar
Chocobozzz committed
4

5
**This guide will present you the following contribution topics:**
Chocobozzz's avatar
Chocobozzz committed
6

Chocobozzz's avatar
Chocobozzz committed
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [Translate](#translate)
- [Give your feedback](#give-your-feedback)
- [Write documentation](#write-documentation)
- [Improve the website](#improve-the-website)
- [Develop](#develop)
  - [Prerequisites](#prerequisites)
  - [Online development](#online-development)
  - [Server side](#server-side)
  - [Client side](#client-side)
  - [Client and server side](#client-and-server-side)
  - [Testing the federation of PeerTube servers](#testing-the-federation-of-peertube-servers)
  - [Unit tests](#unit-tests)
  - [Emails](#emails)
- [Plugins & Themes](#plugins--themes)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
Chocobozzz's avatar
Chocobozzz committed
27

Chocobozzz's avatar
Chocobozzz committed
28
29
30
31
32
## Translate

You can help us to translate the PeerTube interface to many languages! See [the documentation](/support/doc/translation.md) to know how.


Chocobozzz's avatar
Chocobozzz committed
33
34
## Give your feedback

Benjamin Bouvier's avatar
Benjamin Bouvier committed
35
36
37
You don't need to know how to code to start contributing to PeerTube! Other
contributions are very valuable too, among which: you can test the software and
report bugs, you can give feedback on potential bugs, features that you are
38
interested in, user interface, design, decentralized architecture...
Chocobozzz's avatar
Chocobozzz committed
39
40


41
## Write documentation
Chocobozzz's avatar
Chocobozzz committed
42

43
You can help to write the documentation of the REST API, code, architecture,
Chocobozzz's avatar
Chocobozzz committed
44
45
demonstrations.

46
For the REST API you can see the documentation in [/support/doc/api](https://github.com/Chocobozzz/PeerTube/tree/develop/support/doc/api) directory.
Chocobozzz's avatar
Chocobozzz committed
47
Then, you can just open the `openapi.yaml` file in a special editor like [http://editor.swagger.io/](http://editor.swagger.io/) to easily see and edit the documentation. You can also use [redoc-cli](https://github.com/Redocly/redoc/blob/master/cli/README.md) and run `redoc-cli serve --watch support/doc/api/openapi.yaml` to see the final result.
Chocobozzz's avatar
Chocobozzz committed
48
49

Some hints:
50
51
52
 * Routes are defined in [/server/controllers/](https://github.com/Chocobozzz/PeerTube/tree/develop/server/controllers) directory
 * Parameters validators are defined in [/server/middlewares/validators](https://github.com/Chocobozzz/PeerTube/tree/develop/server/middlewares/validators) directory
 * Models sent/received by the controllers are defined in [/shared/models](https://github.com/Chocobozzz/PeerTube/tree/develop/shared/models) directory
Chocobozzz's avatar
Chocobozzz committed
53

Chocobozzz's avatar
Chocobozzz committed
54

55
56
57
58
59
60
61
62
63
## Improve the website

PeerTube's website is [joinpeertube.org](https://joinpeertube.org), where people can learn about the project and how it works – note that it is not a PeerTube instance, but rather the project's homepage.

You can help us improve it too!

It is not hosted on GitHub but on [Framasoft](https://framasoft.org/)'s own [GitLab](https://about.gitlab.com/) instance, [FramaGit](https://framagit.org): https://framagit.org/framasoft/peertube/joinpeertube


64
## Develop
Chocobozzz's avatar
Chocobozzz committed
65

Rigel Kent's avatar
Rigel Kent committed
66
67
68
69
70
71
Always talk about features you want to develop by creating/finding and commenting the issue tackling your problem
before you start working on it, and inform the community that you begin coding by claiming the issue.

Once you are ready to show your code to ask for feedback, submit a *draft* Pull Request.
Once you are ready for a code review before merge, submit a Pull Request. In any case, please
link your PR to the issues it solves by using the GitHub syntax: "fixes #issue_number".
Chocobozzz's avatar
Chocobozzz committed
72

73
### Prerequisites
Chocobozzz's avatar
Chocobozzz committed
74

75
76
First, you should use a server or PC with at least 4GB of RAM. Less RAM may lead to crashes.

77
1) Make sure that you have followed
78
[the steps](/support/doc/dependencies.md)
79
to install the dependencies.
80
81
82
1) Install [parallel](https://www.gnu.org/software/parallel/) to be able to run tests.
1) Fork the Github repository.
1) Run the following commands.
Chocobozzz's avatar
Chocobozzz committed
83
```
84
$ git clone https://github.com/Chocobozzz/PeerTube
85
$ cd PeerTube
86
$ git remote add me git@github.com:YOUR_GITHUB_USERNAME/PeerTube.git
87
88
$ yarn install --pure-lockfile
```
Benjamin Bouvier's avatar
Benjamin Bouvier committed
89

90
91
92
93
Note that development is done on the `develop` branch. If you want to hack on
Peertube, you should switch to that branch. Also note that you have to repeat
the `yarn install --pure-lockfile` command.

94
95
96
97
98
99
When you create a new branch you should also tell to use your repo for upload
not default one. To do just do:
```
$ git push --set-upstream me <your branch name>
```

Benjamin Bouvier's avatar
Benjamin Bouvier committed
100
101
102
103
104
Then, create a postgres database and user with the values set in the
`config/default.yaml` file. For instance, if you do not change the values
there, the following commands would create a new database called `peertube_dev`
and a postgres user called `peertube` with password `peertube`:

Chocobozzz's avatar
Chocobozzz committed
105
```
106
107
108
# sudo -u postgres createuser -P peertube
Enter password for new role: peertube
# sudo -u postgres createdb -O peertube peertube_dev
Benjamin Bouvier's avatar
Benjamin Bouvier committed
109
110
```

111
112
113
114
115
116
117
Then enable extensions PeerTube needs:

```
$ sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_dev
$ sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_dev
```

118
119
In dev mode, administrator username is **root** and password is **test**.

120
121
122
123
124
125
### Online development

You can get a complete PeerTube development setup with Gitpod, a free one-click online IDE for GitHub:

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/Chocobozzz/PeerTube)

Benjamin Bouvier's avatar
Benjamin Bouvier committed
126
127
### Server side

128
You can find a documentation of the server code/architecture [here](https://docs.joinpeertube.org/#/contribute-architecture?id=server-code).
129

Benjamin Bouvier's avatar
Benjamin Bouvier committed
130
131
To develop on the server-side:

Chocobozzz's avatar
Chocobozzz committed
132
```
133
$ npm run dev:server
Benjamin Bouvier's avatar
Benjamin Bouvier committed
134
135
136
137
```

Then, the server will listen on `localhost:9000`. When server source files
change, these are automatically recompiled and the server will automatically
Chocobozzz's avatar
Chocobozzz committed
138
restart.
Benjamin Bouvier's avatar
Benjamin Bouvier committed
139
140
141

### Client side

142
You can find a documentation of the client code/architecture
143
[here](https://docs.joinpeertube.org/#/contribute-architecture?id=client-code).
144
145


Benjamin Bouvier's avatar
Benjamin Bouvier committed
146
147
To develop on the client side:

Chocobozzz's avatar
Chocobozzz committed
148
```
149
$ npm run dev:client
Benjamin Bouvier's avatar
Benjamin Bouvier committed
150
151
152
153
154
```

The API will listen on `localhost:9000` and the frontend on `localhost:3000`.
Client files are automatically compiled on change, and the web browser will
reload them automatically thanks to hot module replacement.
Chocobozzz's avatar
Chocobozzz committed
155

Chocobozzz's avatar
Chocobozzz committed
156
157
158
159
160
161
162
163
164
165
### Client and server side

The API will listen on `localhost:9000` and the frontend on `localhost:3000`.
File changes are automatically recompiled, injected in the web browser (no need to refresh manually)
and the web server is automatically restarted.

```
$ npm run dev
```

Chocobozzz's avatar
Chocobozzz committed
166
167
168
169
170
171
172
173
### RTL layout

To test RTL layout using `ar` locale:

```
$ npm run dev -- --ar-locale
```

Rigel Kent's avatar
Rigel Kent committed
174
175
176
177
178
179
180
181
### Testing

Your code contributions must pass the tests before they can be merged. Tests ensure most of the application behaves
as expected and respect the syntax conventions. They will run upon PR submission as part of our CI, but running them beforehand yourself will get you faster feedback and save CI runner time for others.

PeerTube mainly features backend and plugin tests, found in `server/tests`.

#### Unit tests
Chocobozzz's avatar
Chocobozzz committed
182

183
Create a PostgreSQL user **with the same name as your username** in order to avoid using the *postgres* user.
Rigel Kent's avatar
Rigel Kent committed
184

185
Then, we can create the databases (if they don't already exist):
186
187

```
Rigel Kent's avatar
Rigel Kent committed
188
189
$ sudo -u postgres createuser you_username --createdb --superuser
$ npm run clean:server:test
190
191
```

Rigel Kent's avatar
Rigel Kent committed
192
Build the application and run the unit/integration tests:
Chocobozzz's avatar
Chocobozzz committed
193

Chocobozzz's avatar
Chocobozzz committed
194
```
Chocobozzz's avatar
Chocobozzz committed
195
$ npm run build -- --light
Rigel Kent's avatar
Rigel Kent committed
196
$ npm test
197
198
```

Rigel Kent's avatar
Rigel Kent committed
199
If you just want to run 1 test (which is what you want to debug a specific test rapidly):
200
201

```
Chocobozzz's avatar
Chocobozzz committed
202
$ TS_NODE_FILES=true npm run mocha -- --exit -r ts-node/register -r tsconfig-paths/register --bail server/tests/api/videos/single-server.ts
203
```
Chocobozzz's avatar
Chocobozzz committed
204

205
206
207
208
209
210
While testing, you might want to display a server's logs:

```
NODE_APP_INSTANCE=1 NODE_ENV=test npm run parse-log -- --level debug | less +GF
```

Rigel Kent's avatar
Rigel Kent committed
211
212
Instance configurations are in `config/test-{1,2,3,4,5,6}.yaml`.
Note that only instance 2 has transcoding enabled.
Chocobozzz's avatar
Chocobozzz committed
213

Rigel Kent's avatar
Rigel Kent committed
214
#### Testing the federation of PeerTube servers
Chocobozzz's avatar
Chocobozzz committed
215

216
217
Create a PostgreSQL user **with the same name as your username** in order to avoid using the *postgres* user.
Then, we can create the databases (if they don't already exist):
218
219

```
Rigel Kent's avatar
Rigel Kent committed
220
221
$ sudo -u postgres createuser you_username --createdb
$ createdb -O peertube peertube_test{1,2,3}
222
223
```

Rigel Kent's avatar
Rigel Kent committed
224
Build the application and flush the old tests data:
Chocobozzz's avatar
Chocobozzz committed
225
226

```
227
$ npm run build -- --light
Rigel Kent's avatar
Rigel Kent committed
228
$ npm run clean:server:test
Chocobozzz's avatar
Chocobozzz committed
229
```
Chocobozzz's avatar
Chocobozzz committed
230

Rigel Kent's avatar
Rigel Kent committed
231
This will run 3 nodes:
Chocobozzz's avatar
Chocobozzz committed
232
233

```
Rigel Kent's avatar
Rigel Kent committed
234
$ npm run play
Chocobozzz's avatar
Chocobozzz committed
235
```
236

Rigel Kent's avatar
Rigel Kent committed
237
238
239
240
Then you will get access to the three nodes at `http://localhost:900{1,2,3}`
with the `root` as username and `test{1,2,3}` for the password.

Instance configurations are in `config/test-{1,2,3}.yaml`.
Chocobozzz's avatar
Chocobozzz committed
241

Chocobozzz's avatar
Chocobozzz committed
242
243
244
245
246
247
248
### Emails

To test emails with PeerTube:

 * Run [mailslurper](http://mailslurper.com/)
 * Run PeerTube using mailslurper SMTP port: `NODE_CONFIG='{ "smtp": { "hostname": "localhost", "port": 2500, "tls": false } }' NODE_ENV=test npm start`

Chocobozzz's avatar
Chocobozzz committed
249
250
251
## Plugins & Themes

See the dedicated documentation: https://docs.joinpeertube.org/#/contribute-plugins