diff options
Diffstat (limited to 'support/doc/development')
-rw-r--r-- | support/doc/development/lib.md | 2 | ||||
-rw-r--r-- | support/doc/development/localization.md | 2 | ||||
-rw-r--r-- | support/doc/development/monitoring.md | 4 | ||||
-rw-r--r-- | support/doc/development/server.md | 66 | ||||
-rw-r--r-- | support/doc/development/tests.md | 15 |
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 | ``` |
20 | npm run generate-types-package 4.x.x | 20 | npm run generate-types-package 4.x.x |
21 | cd packages/types/dist | 21 | cd packages/types-generator/dist |
22 | npm publish --access=public | 22 | npm 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 | |||
13 | To benchmark the REST API and save result in `benchmark.json`: | 13 | To benchmark the REST API and save result in `benchmark.json`: |
14 | 14 | ||
15 | ``` | 15 | ``` |
16 | node dist/scripts/benchmark.js -o benchmark.json | 16 | npm run benchmark-server -- -o benchmark.json |
17 | ``` | 17 | ``` |
18 | 18 | ||
19 | You can also grep on a specific test: | 19 | You can also grep on a specific test: |
20 | 20 | ||
21 | ``` | 21 | ``` |
22 | node dist/scripts/benchmark.js --grep homepage | 22 | npm 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 | ||
5 | Sequelize models contain optional fields corresponding to table joins. | 5 | Sequelize models contain optional fields corresponding to table joins. |
6 | For example, `VideoModel` has a `VideoChannel?: VideoChannelModel` field. It can be filled if the SQL query joined with the `videoChannel` table or empty if not. | 6 | For example, `VideoModel` has a `VideoChannel?: VideoChannelModel` field. It can be filled if the SQL query joined with the `videoChannel` table or empty if not. |
7 | It can be difficult in TypeScript to understand if a function argument expects associations to be filled or not. | 7 | It can be difficult in TypeScript to understand if a function argument expects associations to be filled or not. |
8 | To improve clarity and reduce bugs, PeerTube defines multiple versions of a database model depending on its associations in `server/types/models/`. | 8 | To improve clarity and reduce bugs, PeerTube defines multiple versions of a database model depending on its associations in `server/server/types/models/`. |
9 | These 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). | 9 | These 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: | |||
8 | sudo -u postgres createuser you_username --createdb --superuser | 8 | sudo -u postgres createuser you_username --createdb --superuser |
9 | ``` | 9 | ``` |
10 | 10 | ||
11 | Prepare databases: | 11 | Prepare the databases: |
12 | 12 | ||
13 | ```bash | 13 | ```bash |
14 | npm run clean:server:test | 14 | npm run clean:server:test |
@@ -45,22 +45,19 @@ sudo apt-get install parallel libimage-exiftool-perl | |||
45 | 45 | ||
46 | ### Test | 46 | ### Test |
47 | 47 | ||
48 | To run all test suites: | 48 | To run all test suites (can be long!): |
49 | 49 | ||
50 | ```bash | 50 | ```bash |
51 | npm run test # See scripts/test.sh to run a particular suite | 51 | npm run test # See scripts/test.sh to run a particular suite |
52 | ``` | 52 | ``` |
53 | 53 | ||
54 | Most of tests can be run using: | 54 | To run a specific test: |
55 | 55 | ||
56 | ```bash | 56 | ```bash |
57 | TS_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 | 57 | npm 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 |
63 | TS_NODE_FILES=true mocha -- --timeout 30000 --exit -r ts-node/register -r tsconfig-paths/register --bail server/tests/api/activitypub/security.ts | 60 | npm run mocha -- --exit --bail packages/tests/src/api/videos/single-server.ts |
64 | ``` | 61 | ``` |
65 | 62 | ||
66 | ### Configuration | 63 | ### Configuration |