mirror of
https://github.com/vector-im/element-call.git
synced 2026-05-01 09:54:37 +00:00
update linking realted logic
- remove post-commit hook - remove .links.cjs enable/disable (instead just add/rm .pnpmfile.cjs) - rename pnpm links:enable -> pnpm links:on - rename pnpm links:disable -> pnpm links:off - unify doc filenames `-` -> `_` - add linking_concept_reasoning.md to provide background why the linking is how it is.
This commit is contained in:
Timo K
@@ -2,8 +2,8 @@
|
||||
|
||||
This folder contains documentation for setup, usage, and development of Element Call.
|
||||
|
||||
- [Embedded vs standalone mode](./embedded-standalone.md)
|
||||
- [Url format and parameters](./url-params.md)
|
||||
- [Embedded vs standalone mode](./embedded_standalone.md)
|
||||
- [Url format and parameters](./url_params.md)
|
||||
- [Global JS controls](./controls.md)
|
||||
- [Self-Hosting](./self-hosting.md)
|
||||
- [Self-Hosting](./self_hosting.md)
|
||||
- [Developing with linked packages](./linking.md)
|
||||
|
||||
@@ -14,7 +14,7 @@ The table below provides a comparison of the two packages:
|
||||
| **Release artifacts** | Docker Image, Tarball | Tarball, NPM for Web, Android AAR, SwiftPM for iOS |
|
||||
| **Recommended for** | Standalone/guest access usage | Embedding within messenger apps |
|
||||
| **Responsibility for regulatory compliance** | The administrator that is deploying the app is responsible for compliance with any applicable regulations (e.g. privacy) | The developer of the messenger app is responsible for compliance |
|
||||
| **Analytics consent** | Element Call will show a consent UI. | Element Call will not show a consent UI. The messenger app should only provide the embedded Element Call with the [analytics URL parameters](./url-params.md#embedded-only-parameters) if consent has been granted. |
|
||||
| **Analytics consent** | Element Call will show a consent UI. | Element Call will not show a consent UI. The messenger app should only provide the embedded Element Call with the [analytics URL parameters](./url_params.md#embedded-only-parameters) if consent has been granted. |
|
||||
| **Analytics data** | Element Call will send data to the Posthog, Sentry and Open Telemetry targets specified by the administrator in the `config.json` | Element Call will send data to the Posthog and Sentry targets specified in the URL parameters by the messenger app |
|
||||
|
||||
### Using the embedded package within a messenger app
|
||||
@@ -26,7 +26,7 @@ The basics are:
|
||||
1. Add the appropriate platform dependency as given for a [release](https://github.com/element-hq/element-call/releases), or use the embedded tarball. e.g. `npm install @element-hq/element-call-embedded@0.9.0`
|
||||
2. Include the assets from the platform dependency in the build process. e.g. copy the assets during a [Webpack](https://github.com/element-hq/element-web/blob/247cd8d56d832d006d7dfb919d1042529d712b59/webpack.config.js#L677-L682) build.
|
||||
3. Use the `index.html` entrypointof the imported assets when you are constructing the WebView or iframe. e.g. using a [relative path in a webapp](https://github.com/element-hq/element-web/blob/247cd8d56d832d006d7dfb919d1042529d712b59/src/models/Call.ts#L680), or on the the Android [WebViewAssetLoader](https://github.com/element-hq/element-x-android/blob/fe5aab6588ecdcf9354a3bfbd9e97c1b31175a8f/features/call/impl/src/main/kotlin/io/element/android/features/call/impl/utils/DefaultCallWidgetProvider.kt#L20)
|
||||
4. Set any of the [embedded-only URL parameters](./url-params.md#embedded-only-parameters) that you need.
|
||||
4. Set any of the [embedded-only URL parameters](./url_params.md#embedded-only-parameters) that you need.
|
||||
|
||||
## Widget vs standalone mode
|
||||
|
||||
@@ -36,4 +36,4 @@ As a widget, the app only uses the core calling (MatrixRTC) parts. The rest (aut
|
||||
Element Call and the hosting client are connected via the widget API.
|
||||
|
||||
Element Call detects that it is run as a widget if a widgetId is defined in the url parameters. If `widgetId` is present then Element Call will try to connect to the client via the widget postMessage API using the parameters provided in [Url Format and parameters
|
||||
](./url-params.md).
|
||||
](./url_params.md).
|
||||
@@ -1,8 +1,25 @@
|
||||
## Quickstart guide
|
||||
run
|
||||
```bash
|
||||
./scripts/setup-linking.sh
|
||||
```
|
||||
Read the script output:
|
||||
```
|
||||
Setup complete.
|
||||
Update: .links.cjs to your liking
|
||||
Run: 'pnpm links:on' to test your .links.cjs
|
||||
Run: 'git commit' with links enabled to test the git pre-commit hook.
|
||||
Run: 'pnpm links:off' to be able to commit again
|
||||
Run: 'git config --local core.hooksPath ""' to allow committing with linking (not recommended)
|
||||
Run: 'rm links.cjs' & 'git config --local core.hooksPath ""' to fully revert what this script did
|
||||
```
|
||||
|
||||
|
||||
# Developing with linked packages
|
||||
|
||||
If you want to make changes to a package that Element Call depends on and see those changes applied in real time, you can create a link to a local copy of the package. Pnpm has a command for this (`pnpm link`), but it's not recommended to use it as it ends up modifying package.json with details specific to your development environment.
|
||||
If you want to make changes to a package that Element Call depends on and see those changes applied in real time, you can create a link to a local copy of the package. `pnpm` has a command for this (`pnpm link`), but it's not recommended to use it as it ends up modifying package.json with details specific to your development environment.
|
||||
|
||||
Instead, you can use our little 'linker' plugin. Create a file named `.links.cjs` in the Element Call project directory, listing the names and paths of any dependencies you want to link. For example:
|
||||
Instead, create a file named `.links.cjs` in the Element Call project directory (or run `./scripts/setup-linking.sh` to create a template), listing the names and paths of any dependencies you want to link. For example:
|
||||
|
||||
```cjs
|
||||
// Packages to link to local checkouts
|
||||
@@ -12,32 +29,32 @@ module.exports = {
|
||||
};
|
||||
```
|
||||
|
||||
Then run `pnpm install`.
|
||||
Then run `pnpm links:on`. (this will activate the pnpm file + run `pnpm install` to setup the linking)
|
||||
|
||||
## Hooks
|
||||
|
||||
Changes in `.links.yaml` will also update `pnpm-lock.yaml` when `pnpm` is executed. The lockfile will then contain the local
|
||||
Changes in `.links.cjs` will also update `pnpm-lock.yaml` when `pnpm install` is executed. The lockfile will then contain the local
|
||||
version of the package which would not work on others dev setups or the github CI.
|
||||
|
||||
One always needs to run:
|
||||
One always needs to remove the pnpm `readPackage` script (the `.pnpmfile.cjs`) and run:
|
||||
|
||||
```bash
|
||||
mv .links.cjs .links.disabled.cjs
|
||||
pnpm install
|
||||
```
|
||||
|
||||
before committing a change.
|
||||
|
||||
To make it more convenient to work with this linking system we added git hooks.
|
||||
A `pre-commit` hook will run `mv .links.yaml .links.disabled.yaml`, `pnpm install` and `git add yarn.lock` if it detects
|
||||
a `.links.yaml` file and abort the commit.
|
||||
You will than need to check if the resulting changes are appropriate and commit again.
|
||||
To make this less of a foot gun we added a git hook.
|
||||
A `pre-commit` hook will check if linking is currently used. If it detects
|
||||
a `.pnpmfile.cjs` file it will abort the commit with an explanatory message.
|
||||
You will than need to run `pnpm links:off` and commit again.
|
||||
|
||||
A `post-commit` hook will setup the linking as it was
|
||||
before if a `.links.disabled.cjs` is present. It runs `mv .links.disabled.cjs .links.cjs` and `pnpm install`.
|
||||
|
||||
To activate the hooks automatically configure git with
|
||||
To activate the hooks configure git with (when using the setup script (`./scripts/setup-linking.sh`) this is already done):
|
||||
|
||||
```bash
|
||||
git config --local core.hooksPath .githooks
|
||||
```
|
||||
This will add the hook path for this repository only to .gihooks. which is a tracked (by git) folder containing the pre-commit hook.
|
||||
|
||||
## Background
|
||||
Information, why this approach is used can be found in the [linking concept reasoning](./linking_concept_reasoning.md) document.
|
||||
|
||||
27
docs/linking_concept_reasoning.md
Normal file
27
docs/linking_concept_reasoning.md
Normal file
@@ -0,0 +1,27 @@
|
||||
|
||||
### Why do we not enable .pnpmfile.cjs by default
|
||||
Background: The presence of the `.pnpmfile.cjs` adds a field to the `pnpm-lock.yaml` called: `pnpmfileChecksum`. This field is a checksum of the content of the `.pnpmfile.cjs` file.
|
||||
`pnpm install --frozen-lockfile` **fails** if there is a `.pnpmfile.cjs` but no `pnpmfileChecksum` or vice versa (or on mismatch).
|
||||
|
||||
_TLDR: running with `--ignore-pnpmfile` will fail if `pnpmfileChecksum` is present._
|
||||
|
||||
#### `pnpmfileChecksum` + renovate bot
|
||||
When the renovate bot creates a PR it runs `pnpm install --ignore-pnpmfile`. This means that the `pnpmfileChecksum` in the lockfile will be **empty**.
|
||||
This breaks builds that **don't** ignore the `.pnpmfile.cjs`-file. (CI that runs on the renovate PR)
|
||||
From here we have two possible paths:
|
||||
- ignore `.pnpmfile.cjs` in all CI builds CI will also fail if we accidently add it locally.
|
||||
- fixup the `pnpm-lock.yaml` in the renovate PR to contain the correct `pnpmfileChecksum`.
|
||||
|
||||
Ignoring in all CI builds means that CI will always fail if we enable the linking system.
|
||||
This is annoying but can be worked around with the git hook we provide that at least lets us know that we are
|
||||
commiting with enabled linking.
|
||||
Only if we remember setting it back/disbale linking (or let ourselves remember by the git hook) the CI will work.
|
||||
|
||||
#### Summary
|
||||
- We will always run into conflicts with the `pnpmfileChecksum` because in renovate prs it will be empty (`--ignore-pnpmfile`)
|
||||
- To keep it simple we set `--ignore-pnpmfile` in all of ours CI to see issues immediately.
|
||||
- The only solution is to never have a `.pnpmfile.cjs` in the repository when pushing.
|
||||
- This way there will never be a commit with `pnpmfileChecksum` in the lockfile.
|
||||
- renovate (which uses `--ignore-pnpmfile` which we cannot disable) and other CI will work
|
||||
- We are able to use the linking system locally if we `cp` this file from the scripts folder into `./` on demand.
|
||||
- `pnpm links:on` and `pnpm links:off` + `./scripts/setup-linking.sh` will help us with this.
|
||||
@@ -4,7 +4,7 @@ There are two formats for Element Call URLs.
|
||||
|
||||
## Link for sharing
|
||||
|
||||
Requires Element Call to be deployed in [standalone](./embedded-standalone.md) mode.
|
||||
Requires Element Call to be deployed in [standalone](./embedded_standalone.md) mode.
|
||||
|
||||
```text
|
||||
https://element_call.domain/room/#
|
||||
@@ -36,15 +36,15 @@ possible to support encryption.
|
||||
|
||||
| Package | Deployment | URL |
|
||||
| ------------------------------------ | ----------------------------- | ----------------------------------------------------------------------------- |
|
||||
| [Full](./embedded-standalone.md) | All | `https://element_call.domain/room` |
|
||||
| [Embedded](./embedded-standalone.md) | Remote URL | `https://element_call.domain/` n.b. no `/room` part |
|
||||
| [Embedded](./embedded-standalone.md) | Embedded within messenger app | Platform dependent, but you load the `index.html` file without a `/room` part |
|
||||
| [Full](./embedded_standalone.md) | All | `https://element_call.domain/room` |
|
||||
| [Embedded](./embedded_standalone.md) | Remote URL | `https://element_call.domain/` n.b. no `/room` part |
|
||||
| [Embedded](./embedded_standalone.md) | Embedded within messenger app | Platform dependent, but you load the `index.html` file without a `/room` part |
|
||||
|
||||
## Parameters
|
||||
|
||||
### Common Parameters
|
||||
|
||||
These parameters are relevant to both [widget](./embedded-standalone.md) and [standalone](./embedded-standalone.md) modes:
|
||||
These parameters are relevant to both [widget](./embedded_standalone.md) and [standalone](./embedded_standalone.md) modes:
|
||||
|
||||
| Name | Values | Required for widget | Required for SPA | Description |
|
||||
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@@ -74,7 +74,7 @@ These parameters are relevant to both [widget](./embedded-standalone.md) and [st
|
||||
|
||||
### Widget-only parameters
|
||||
|
||||
These parameters are only supported in [widget](./embedded-standalone.md) mode.
|
||||
These parameters are only supported in [widget](./embedded_standalone.md) mode.
|
||||
|
||||
| Name | Values | Required | Description |
|
||||
| --------------- | ----------------------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@@ -89,7 +89,7 @@ These parameters are only supported in [widget](./embedded-standalone.md) mode.
|
||||
|
||||
### Embedded-only parameters
|
||||
|
||||
These parameters are only supported in the [embedded](./embedded-standalone.md) package of Element Call and will be ignored in the [full](./embedded-standalone.md) package.
|
||||
These parameters are only supported in the [embedded](./embedded_standalone.md) package of Element Call and will be ignored in the [full](./embedded_standalone.md) package.
|
||||
|
||||
| Name | Values | Required | Description |
|
||||
| -------------------- | -------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||||
Reference in New Issue
Block a user