aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/development
diff options
context:
space:
mode:
Diffstat (limited to 'support/doc/development')
-rw-r--r--support/doc/development/lib.md2
-rw-r--r--support/doc/development/localization.md2
-rw-r--r--support/doc/development/monitoring.md4
-rw-r--r--support/doc/development/server.md66
-rw-r--r--support/doc/development/tests.md15
5 files changed, 43 insertions, 46 deletions
diff --git a/support/doc/development/lib.md b/support/doc/development/lib.md
index 25fe3068e..1ea09f2bc 100644
--- a/support/doc/development/lib.md
+++ b/support/doc/development/lib.md
@@ -18,7 +18,7 @@ The complete types package is generated via:
18 18
19``` 19```
20npm run generate-types-package 4.x.x 20npm run generate-types-package 4.x.x
21cd packages/types/dist 21cd packages/types-generator/dist
22npm publish --access=public 22npm publish --access=public
23``` 23```
24 24
diff --git a/support/doc/development/localization.md b/support/doc/development/localization.md
index a38ed6f55..4aca9b18b 100644
--- a/support/doc/development/localization.md
+++ b/support/doc/development/localization.md
@@ -26,7 +26,7 @@ Nothing to do here, Github will automatically send a webhook to Weblate that wil
26 26
27## Support a new language 27## Support a new language
28 28
29 * Add it to [/shared/models/i18n/i18n.ts](/shared/models/i18n/i18n.ts) 29 * Add it to [/packages/models/i18n/i18n.ts](/packages/models/i18n/i18n.ts)
30 * Add it to [/scripts/build/client.sh](/scripts/build/client.sh) 30 * Add it to [/scripts/build/client.sh](/scripts/build/client.sh)
31 * Add it to [/client/angular.json](/client/angular.json) 31 * Add it to [/client/angular.json](/client/angular.json)
32 * Add it to [/scripts/i18n/update.sh](/scripts/i18n/update.sh) 32 * Add it to [/scripts/i18n/update.sh](/scripts/i18n/update.sh)
diff --git a/support/doc/development/monitoring.md b/support/doc/development/monitoring.md
index 93fd1403e..023be9e92 100644
--- a/support/doc/development/monitoring.md
+++ b/support/doc/development/monitoring.md
@@ -13,11 +13,11 @@ npm run build -- --analyze-bundle && npm run client-report
13To benchmark the REST API and save result in `benchmark.json`: 13To benchmark the REST API and save result in `benchmark.json`:
14 14
15``` 15```
16node dist/scripts/benchmark.js -o benchmark.json 16npm run benchmark-server -- -o benchmark.json
17``` 17```
18 18
19You can also grep on a specific test: 19You can also grep on a specific test:
20 20
21``` 21```
22node dist/scripts/benchmark.js --grep homepage 22npm run benchmark-server -- --grep homepage
23``` 23```
diff --git a/support/doc/development/server.md b/support/doc/development/server.md
index 7a9fa571f..5c83af704 100644
--- a/support/doc/development/server.md
+++ b/support/doc/development/server.md
@@ -1,11 +1,11 @@
1# Server code 1 # Server code
2 2
3## Database model typing 3## Database model typing
4 4
5Sequelize models contain optional fields corresponding to table joins. 5Sequelize models contain optional fields corresponding to table joins.
6For example, `VideoModel` has a `VideoChannel?: VideoChannelModel` field. It can be filled if the SQL query joined with the `videoChannel` table or empty if not. 6For example, `VideoModel` has a `VideoChannel?: VideoChannelModel` field. It can be filled if the SQL query joined with the `videoChannel` table or empty if not.
7It can be difficult in TypeScript to understand if a function argument expects associations to be filled or not. 7It can be difficult in TypeScript to understand if a function argument expects associations to be filled or not.
8To improve clarity and reduce bugs, PeerTube defines multiple versions of a database model depending on its associations in `server/types/models/`. 8To improve clarity and reduce bugs, PeerTube defines multiple versions of a database model depending on its associations in `server/server/types/models/`.
9These models start with `M` and by default do not include any association. `MVideo` for example corresponds to `VideoModel` without any association, where `VideoChannel` attribute doesn't exist. On the other hand, `MVideoWithChannel` is a `MVideo` that has a `VideoChannel` field. This way, a function that accepts `video: MVideoWithChannel` argument expects a video with channel populated. Main PeerTube code should never use `...Model` (`VideoModel`) database type, but always `M...` instead (`MVideo`, `MVideoChannel` etc). 9These models start with `M` and by default do not include any association. `MVideo` for example corresponds to `VideoModel` without any association, where `VideoChannel` attribute doesn't exist. On the other hand, `MVideoWithChannel` is a `MVideo` that has a `VideoChannel` field. This way, a function that accepts `video: MVideoWithChannel` argument expects a video with channel populated. Main PeerTube code should never use `...Model` (`VideoModel`) database type, but always `M...` instead (`MVideo`, `MVideoChannel` etc).
10 10
11## Add a new feature walkthrough 11## Add a new feature walkthrough
@@ -16,67 +16,67 @@ Some of these may be optional (for example your new endpoint may not need to sen
16 * Configuration: 16 * Configuration:
17 - Add you new configuration key in `config/default.yaml` and `config/production.yaml` 17 - Add you new configuration key in `config/default.yaml` and `config/production.yaml`
18 - If you configuration needs to be different in dev or tests environments, also update `config/dev.yaml` and `config/test.yaml` 18 - If you configuration needs to be different in dev or tests environments, also update `config/dev.yaml` and `config/test.yaml`
19 - Load your configuration in `server/initializers/config.ts` 19 - Load your configuration in `server/server/initializers/config.ts`
20 - Check new configuration keys are set in `server/initializers/checker-before-init.ts` 20 - Check new configuration keys are set in `server/server/initializers/checker-before-init.ts`
21 - You can also ensure configuration consistency in `server/initializers/checker-after-init.ts` 21 - You can also ensure configuration consistency in `server/server/initializers/checker-after-init.ts`
22 - If you want your configuration to be available in the client: 22 - If you want your configuration to be available in the client:
23 + Add your field in `shared/models/server/server-config.model.ts` 23 + Add your field in `packages/models/server/server/server-config.model.ts`
24 + Update `server/lib/server-config-manager.ts` to include your new configuration 24 + Update `server/server/lib/server-config-manager.ts` to include your new configuration
25 - If you want your configuration to be updatable by the web admin in the client: 25 - If you want your configuration to be updatable by the web admin in the client:
26 + Add your field in `shared/models/server/custom-config.model.ts` 26 + Add your field in `packages/models/server/server/custom-config.model.ts`
27 + Add the configuration to the config object in the `server/controllers/api/config.ts` controller 27 + Add the configuration to the config object in the `server/server/controllers/api/config.ts` controller
28 * Controllers: 28 * Controllers:
29 - Create the controller file and fill it with your REST API routes 29 - Create the controller file and fill it with your REST API routes
30 - Import and use your controller in the parent controller 30 - Import and use your controller in the parent controller
31 * Middlewares: 31 * Middlewares:
32 - Create your validator middleware in `server/middlewares/validators` that will be used by your controllers 32 - Create your validator middleware in `server/server/middlewares/validators` that will be used by your controllers
33 - Add your new middleware file `server/middlewares/validators/index.ts` so it's easier to import 33 - Add your new middleware file `server/server/middlewares/validators/index.ts` so it's easier to import
34 - Create the entry in `server/types/express.d.ts` to attach the database model loaded by your middleware to the express response 34 - Create the entry in `server/server/types/express.d.ts` to attach the database model loaded by your middleware to the express response
35 * Validators: 35 * Validators:
36 - Create your validators that will be used by your middlewares in `server/helpers/custom-validators` 36 - Create your validators that will be used by your middlewares in `server/server/helpers/custom-validators`
37 * Typescript models: 37 * Typescript models:
38 - Create the API models (request parameters or response) in `shared/models` 38 - Create the API models (request parameters or response) in `packages/models`
39 - Add your models in `index.ts` of current directory to facilitate the imports 39 - Add your models in `index.ts` of current directory to facilitate the imports
40 * Sequelize model (BDD): 40 * Sequelize model (BDD):
41 - If you need to create a new table: 41 - If you need to create a new table:
42 + Create the Sequelize model in `server/models/`: 42 + Create the Sequelize model in `server/server/models/`:
43 * Create the `@Column` 43 * Create the `@Column`
44 * Add some indexes if you need 44 * Add some indexes if you need
45 * Create static methods to load a specific from the database `loadBy...` 45 * Create static methods to load a specific from the database `loadBy...`
46 * Create static methods to load a list of models from the database `listBy...` 46 * Create static methods to load a list of models from the database `listBy...`
47 * Create the instance method `toFormattedJSON` that creates the JSON to send to the REST API from the model 47 * Create the instance method `toFormattedJSON` that creates the JSON to send to the REST API from the model
48 + Add your new Sequelize model to `server/initializers/database.ts` 48 + Add your new Sequelize model to `server/server/initializers/database.ts`
49 + Create a new file in `server/types` to define multiple versions of your Sequelize model depending on database associations 49 + Create a new file in `server/server/types` to define multiple versions of your Sequelize model depending on database associations
50 + Add this new file to `server/types/*/index.ts` to facilitate the imports 50 + Add this new file to `server/server/types/*/index.ts` to facilitate the imports
51 + Create database migrations: 51 + Create database migrations:
52 * Create the migration file in `server/initializers/migrations` using raw SQL (copy the same SQL query as at PeerTube startup) 52 * Create the migration file in `server/server/initializers/migrations` using raw SQL (copy the same SQL query as at PeerTube startup)
53 * Update `LAST_MIGRATION_VERSION` in `server/initializers/constants.ts` 53 * Update `LAST_MIGRATION_VERSION` in `server/server/initializers/constants.ts`
54 - If updating database schema (adding/removing/renaming a column): 54 - If updating database schema (adding/removing/renaming a column):
55 + Update the sequelize models in `server/models/` 55 + Update the sequelize models in `server/server/models/`
56 + Add migrations: 56 + Add migrations:
57 * Create the migration file in `initializers/migrations` using Sequelize Query Interface (`.addColumn`, `.dropTable`, `.changeColumn`) 57 * Create the migration file in `initializers/migrations` using Sequelize Query Interface (`.addColumn`, `.dropTable`, `.changeColumn`)
58 * Update `LAST_MIGRATION_VERSION` in `server/initializers/constants.ts` 58 * Update `LAST_MIGRATION_VERSION` in `server/server/initializers/constants.ts`
59 * Notifications: 59 * Notifications:
60 - Create the new notification model in `shared/models/users/user-notification.model.ts` 60 - Create the new notification model in `packages/models/users/user-notification.model.ts`
61 - Create the notification logic in `server/lib/notifier/shared`: 61 - Create the notification logic in `server/server/lib/notifier/shared`:
62 + Email subject has a common prefix (defined by the admin in PeerTube configuration) 62 + Email subject has a common prefix (defined by the admin in PeerTube configuration)
63 - Add your notification to `server/lib/notifier/notifier.ts` 63 - Add your notification to `server/server/lib/notifier/notifier.ts`
64 - Create the email template in `server/lib/emails`: 64 - Create the email template in `server/server/lib/emails`:
65 + A text version is automatically generated from the HTML 65 + A text version is automatically generated from the HTML
66 + The template usually extends `../common/grettings` that already says "Hi" and "Cheers". You just have to write the title and the content blocks that will be inserted in the appropriate places in the HTML template 66 + The template usually extends `../common/grettings` that already says "Hi" and "Cheers". You just have to write the title and the content blocks that will be inserted in the appropriate places in the HTML template
67 - If you need to associate a new table with `userNotification`: 67 - If you need to associate a new table with `userNotification`:
68 + Associate the new table in `UserNotificationModel` (don't forget the index) 68 + Associate the new table in `UserNotificationModel` (don't forget the index)
69 + Add the object property in the API model definition (`shared/models/users/user-notification.model.ts`) 69 + Add the object property in the API model definition (`packages/models/users/user-notification.model.ts`)
70 + Add the object in `UserNotificationModel.toFormattedJSON` 70 + Add the object in `UserNotificationModel.toFormattedJSON`
71 + Handle this new notification type in client (`UserNotificationsComponent`) 71 + Handle this new notification type in client (`UserNotificationsComponent`)
72 + Handle the new object property in client model (`UserNotification`) 72 + Handle the new object property in client model (`UserNotification`)
73 * Tests: 73 * Tests:
74 - Create your command class in `shared/server-commands/` that will wrap HTTP requests to your new endpoint 74 - Create your command class in `packages/server-commands/` that will wrap HTTP requests to your new endpoint
75 - Add your command file in `index.ts` of current directory 75 - Add your command file in `index.ts` of current directory
76 - Instantiate your command class in `shared/server-commands/server/server.ts` 76 - Instantiate your command class in `packages/server-commands/server/server/server.ts`
77 - Create your test file in `server/tests/api/check-params` to test middleware validators/authentification/user rights (offensive tests) 77 - Create your test file in `server/server/tests/api/check-params` to test middleware validators/authentification/user rights (offensive tests)
78 - Add it to `server/tests/api/check-params/index.ts` 78 - Add it to `server/server/tests/api/check-params/index.ts`
79 - Create your test file in `server/tests/api` to test your new endpoints 79 - Create your test file in `server/server/tests/api` to test your new endpoints
80 - Add it to `index.ts` of current directory 80 - Add it to `index.ts` of current directory
81 - Add your notification test in `server/tests/api/notifications` 81 - Add your notification test in `server/server/tests/api/notifications`
82 * Update REST API documentation in `support/doc/api/openapi.yaml` 82 * Update REST API documentation in `support/doc/api/openapi.yaml`
diff --git a/support/doc/development/tests.md b/support/doc/development/tests.md
index 1c2589c8a..2e4c6ff6a 100644
--- a/support/doc/development/tests.md
+++ b/support/doc/development/tests.md
@@ -8,7 +8,7 @@ Prepare PostgreSQL user so PeerTube can delete/create the test databases:
8sudo -u postgres createuser you_username --createdb --superuser 8sudo -u postgres createuser you_username --createdb --superuser
9``` 9```
10 10
11Prepare databases: 11Prepare the databases:
12 12
13```bash 13```bash
14npm run clean:server:test 14npm run clean:server:test
@@ -45,22 +45,19 @@ sudo apt-get install parallel libimage-exiftool-perl
45 45
46### Test 46### Test
47 47
48To run all test suites: 48To run all test suites (can be long!):
49 49
50```bash 50```bash
51npm run test # See scripts/test.sh to run a particular suite 51npm run test # See scripts/test.sh to run a particular suite
52``` 52```
53 53
54Most of tests can be run using: 54To run a specific test:
55 55
56```bash 56```bash
57TS_NODE_TRANSPILE_ONLY=true npm run mocha -- --timeout 30000 --exit -r ts-node/register -r tsconfig-paths/register --bail server/tests/api/videos/video-transcoder.ts 57npm run mocha -- --exit --bail packages/tests/src/your-test.ts
58```
59
60`server/tests/api/activitypub` tests will need different options:
61 58
62``` 59# For example
63TS_NODE_FILES=true mocha -- --timeout 30000 --exit -r ts-node/register -r tsconfig-paths/register --bail server/tests/api/activitypub/security.ts 60npm run mocha -- --exit --bail packages/tests/src/api/videos/single-server.ts
64``` 61```
65 62
66### Configuration 63### Configuration