]> git.immae.eu Git - github/Chocobozzz/PeerTube.git/blame - .github/CONTRIBUTING.md
Increase test timeout
[github/Chocobozzz/PeerTube.git] / .github / CONTRIBUTING.md
CommitLineData
7a7edb72
C
1# Welcome to the contributing guide for PeerTube
2
71607e4a 3Interested in contributing? Awesome!
7a7edb72 4
e2266e4f 5**This guide will present you the following contribution topics:**
7a7edb72 6
17b07dc5
C
7<!-- START doctoc generated TOC please keep comment here to allow auto update -->
8<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
9
17b07dc5
C
10- [Translate](#translate)
11- [Give your feedback](#give-your-feedback)
12- [Write documentation](#write-documentation)
13- [Improve the website](#improve-the-website)
14- [Develop](#develop)
15 - [Prerequisites](#prerequisites)
16 - [Online development](#online-development)
17 - [Server side](#server-side)
18 - [Client side](#client-side)
19 - [Client and server side](#client-and-server-side)
4f97f583
C
20 - [RTL layout](#rtl-layout)
21 - [Testing](#testing)
82029912 22 - [Unit/integration tests](#unitintegration-tests)
4f97f583 23 - [Testing the federation of PeerTube servers](#testing-the-federation-of-peertube-servers)
17b07dc5
C
24 - [Emails](#emails)
25- [Plugins & Themes](#plugins--themes)
26
27<!-- END doctoc generated TOC please keep comment here to allow auto update -->
7a7edb72 28
6a1787c1
C
29## Translate
30
31You can help us to translate the PeerTube interface to many languages! See [the documentation](/support/doc/translation.md) to know how.
32
33
7a7edb72
C
34## Give your feedback
35
e755a63a
BB
36You don't need to know how to code to start contributing to PeerTube! Other
37contributions are very valuable too, among which: you can test the software and
38report bugs, you can give feedback on potential bugs, features that you are
63bfad7e 39interested in, user interface, design, decentralized architecture...
7a7edb72
C
40
41
63bfad7e 42## Write documentation
7a7edb72 43
63bfad7e 44You can help to write the documentation of the REST API, code, architecture,
d59a8da8
C
45demonstrations.
46
0ceadb35 47For the REST API you can see the documentation in [/support/doc/api](https://github.com/Chocobozzz/PeerTube/tree/develop/support/doc/api) directory.
17b07dc5 48Then, 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.
d59a8da8
C
49
50Some hints:
0ceadb35
C
51 * Routes are defined in [/server/controllers/](https://github.com/Chocobozzz/PeerTube/tree/develop/server/controllers) directory
52 * Parameters validators are defined in [/server/middlewares/validators](https://github.com/Chocobozzz/PeerTube/tree/develop/server/middlewares/validators) directory
53 * Models sent/received by the controllers are defined in [/shared/models](https://github.com/Chocobozzz/PeerTube/tree/develop/shared/models) directory
d59a8da8 54
7a7edb72 55
0e62b72b
TK
56## Improve the website
57
58PeerTube'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.
59
60You can help us improve it too!
61
62It 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
63
64
63bfad7e 65## Develop
7a7edb72 66
a3e6d181
RK
67Always talk about features you want to develop by creating/finding and commenting the issue tackling your problem
68before you start working on it, and inform the community that you begin coding by claiming the issue.
69
70Once you are ready to show your code to ask for feedback, submit a *draft* Pull Request.
71Once you are ready for a code review before merge, submit a Pull Request. In any case, please
72link your PR to the issues it solves by using the GitHub syntax: "fixes #issue_number".
7a7edb72 73
63bfad7e 74### Prerequisites
7a7edb72 75
a43e2182 76First, you should use a server or PC with at least 4GB of RAM. Less RAM may lead to crashes.
77
05e85b59 781) Make sure that you have followed
0cfcbae8 79[the steps](/support/doc/dependencies.md)
6676056a 80to install the dependencies.
05e85b59 811) Install [parallel](https://www.gnu.org/software/parallel/) to be able to run tests.
821) Fork the Github repository.
831) Run the following commands.
afe81767 84```
b30acc0e 85$ git clone https://github.com/Chocobozzz/PeerTube
63bfad7e 86$ cd PeerTube
b4bc269e 87$ git remote add me git@github.com:YOUR_GITHUB_USERNAME/PeerTube.git
63bfad7e
C
88$ yarn install --pure-lockfile
89```
e755a63a 90
dd07afa5
FA
91Note that development is done on the `develop` branch. If you want to hack on
92Peertube, you should switch to that branch. Also note that you have to repeat
93the `yarn install --pure-lockfile` command.
94
b30acc0e
J
95When you create a new branch you should also tell to use your repo for upload
96not default one. To do just do:
97```
98$ git push --set-upstream me <your branch name>
99```
100
e755a63a
BB
101Then, create a postgres database and user with the values set in the
102`config/default.yaml` file. For instance, if you do not change the values
103there, the following commands would create a new database called `peertube_dev`
104and a postgres user called `peertube` with password `peertube`:
105
afe81767 106```
63bfad7e
C
107# sudo -u postgres createuser -P peertube
108Enter password for new role: peertube
109# sudo -u postgres createdb -O peertube peertube_dev
e755a63a
BB
110```
111
dd07afa5
FA
112Then enable extensions PeerTube needs:
113
114```
115$ sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_dev
116$ sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_dev
117```
118
63bfad7e
C
119In dev mode, administrator username is **root** and password is **test**.
120
0cfcbae8
JK
121### Online development
122
123You can get a complete PeerTube development setup with Gitpod, a free one-click online IDE for GitHub:
124
125[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/Chocobozzz/PeerTube)
126
e755a63a
BB
127### Server side
128
85cba7f1 129You can find a documentation of the server code/architecture [here](https://docs.joinpeertube.org/contribute-architecture?id=server-code).
63bfad7e 130
e755a63a
BB
131To develop on the server-side:
132
afe81767 133```
63bfad7e 134$ npm run dev:server
e755a63a
BB
135```
136
137Then, the server will listen on `localhost:9000`. When server source files
138change, these are automatically recompiled and the server will automatically
19096851 139restart.
e755a63a
BB
140
141### Client side
142
838f4a79 143You can find a documentation of the client code/architecture
85cba7f1 144[here](https://docs.joinpeertube.org/contribute-architecture?id=client-code).
63bfad7e
C
145
146
e755a63a
BB
147To develop on the client side:
148
afe81767 149```
63bfad7e 150$ npm run dev:client
e755a63a
BB
151```
152
153The API will listen on `localhost:9000` and the frontend on `localhost:3000`.
154Client files are automatically compiled on change, and the web browser will
155reload them automatically thanks to hot module replacement.
7a7edb72 156
19096851
C
157### Client and server side
158
159The API will listen on `localhost:9000` and the frontend on `localhost:3000`.
160File changes are automatically recompiled, injected in the web browser (no need to refresh manually)
161and the web server is automatically restarted.
162
163```
164$ npm run dev
165```
166
27bc9586
C
167### RTL layout
168
169To test RTL layout using `ar` locale:
170
171```
172$ npm run dev -- --ar-locale
173```
174
a3e6d181
RK
175### Testing
176
9883e60f
C
177#### Unit/integration tests
178
a3e6d181
RK
179Your code contributions must pass the tests before they can be merged. Tests ensure most of the application behaves
180as 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.
181
9883e60f 182See the [dedicated documentation](/support/doc/development/tests.md) to run tests locally.
19096851 183
a3e6d181 184#### Testing the federation of PeerTube servers
19096851 185
a9ab599e
C
186Create a PostgreSQL user **with the same name as your username** in order to avoid using the *postgres* user.
187Then, we can create the databases (if they don't already exist):
a2897212
C
188
189```
a3e6d181
RK
190$ sudo -u postgres createuser you_username --createdb
191$ createdb -O peertube peertube_test{1,2,3}
a2897212
C
192```
193
a3e6d181 194Build the application and flush the old tests data:
19096851
C
195
196```
4f97f583 197$ npm run build
a3e6d181 198$ npm run clean:server:test
19096851 199```
76434ec8 200
4f97f583 201To run 3 nodes:
76434ec8
C
202
203```
4f97f583
C
204$ NODE_APP_INSTANCE=1 NODE_ENV=test npm start
205$ NODE_APP_INSTANCE=2 NODE_ENV=test npm start
206$ NODE_APP_INSTANCE=3 NODE_ENV=test npm start
76434ec8 207```
dbe868c0 208
a3e6d181
RK
209Then you will get access to the three nodes at `http://localhost:900{1,2,3}`
210with the `root` as username and `test{1,2,3}` for the password.
211
212Instance configurations are in `config/test-{1,2,3}.yaml`.
bfa1a32b 213
17b07dc5
C
214### Emails
215
216To test emails with PeerTube:
217
218 * Run [mailslurper](http://mailslurper.com/)
219 * Run PeerTube using mailslurper SMTP port: `NODE_CONFIG='{ "smtp": { "hostname": "localhost", "port": 2500, "tls": false } }' NODE_ENV=test npm start`
220
bfa1a32b
C
221## Plugins & Themes
222
85cba7f1 223See the dedicated documentation: https://docs.joinpeertube.org/contribute-plugins