Merge branch 'livekit' into toger5/contribut-issue-first

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,4 +1,11 @@
-<!-- Thanks for submitting a PR! Please ensure the following requirements are met in order for us to review your PR -->
+<!-- Thanks for submitting a PR! Please read CONTRIBUTING.md before you start. -->
+
+> [!IMPORTANT]
+> **Features and UI changes require a pre-approved issue.**
+> Every PR must have a linked issue
+> that a maintainer has reviewed and approved **before you started writing code**.
+> PRs that don't meet this requirement will not be reviewed.
+> See [CONTRIBUTING.md](https://github.com/element-hq/element-call/blob/livekit/CONTRIBUTING.md) for ElementCall decided for this approach.
 
 ## Content
 
@@ -6,34 +13,34 @@
 
 ## Motivation and context
 
-<!-- Provide link to the corresponding issue if applicable or explain the context -->
+<!-- Provide a link to the pre-approved issue, or explain the context for a bug fix -->
 
 ## Screenshots / GIFs
 
 <!--
 
-You can use a table like this to show screenshots comparison.
-Uncomment this markdown table below and edit the last line `|||`:
-|copy screenshot of before here|copy screenshot of after here|
+You can use a table like this to show a before/after comparison.
+Uncomment the markdown table below and fill in the last line:
 
 |Before|After|
 |-|-|
 |||
- -->
+
+-->
 
 ## Tests
 
-<!-- Explain how you tested your development -->
+<!-- Explain how you tested your changes -->
 
 - Step 1
 - Step 2
 - Step ...
--
 
 ## Checklist
 
-- [ ] I have read through [CONTRIBUTING.md](https://github.com/element-hq/element-call/blob/livekit/CONTRIBUTING.md).
-- [ ] Pull request includes screenshots or videos if containing UI changes
-- [ ] Tests written for new code (and old code if feasible).
+- [ ] A linked, pre-approved issue exists for this feature or UI change.
+- [ ] I have read [CONTRIBUTING.md](https://github.com/element-hq/element-call/blob/livekit/CONTRIBUTING.md) in full.
+- [ ] Pull request includes screenshots or videos for any UI changes.
+- [ ] Tests written for new code (and existing touched code where feasible).
 - [ ] Linter and other CI checks pass.
 - [ ] I have licensed the changes to Element by completing the [Contributor License Agreement (CLA)](https://cla-assistant.io/element-hq/element-call)

.github/workflows/build.yaml

@@ -85,31 +85,3 @@ jobs:
       SENTRY_URL: ${{ secrets.SENTRY_URL }}
       SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-
-  build_storybook:
-    name: Build Storybook
-    if: contains(github.event.pull_request.labels.*.name, 'storybook build')
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-        with:
-          persist-credentials: false
-      - name: Enable Corepack
-        run: corepack enable
-      - name: pnpm cache
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          cache: "pnpm"
-          node-version-file: ".node-version"
-      - name: Install dependencies
-        run: "pnpm install --frozen-lockfile --ignore-pnpmfile"
-      - name: Build Storybook
-        run: pnpm run build-storybook
-      - name: Upload Artifact
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
-        with:
-          name: build-output-storybook
-          path: storybook-static
-          # We'll only use this in a triggered job, then we're done with it
-          retention-days: 1

.github/workflows/deploy-to-netlify.yaml

@@ -17,7 +17,7 @@ on:
       package:
         required: true
         type: string
-        description: Which package to deploy - 'full', 'embedded', 'sdk', or 'storybook'
+        description: Which package to deploy - 'full', 'embedded', or 'sdk'
       artifact_run_id:
         required: false
         type: string
@@ -43,7 +43,7 @@ jobs:
         with:
           step: start
           token: ${{ secrets.GITHUB_TOKEN }}
-          env: ${{ inputs.package}}
+          env: Netlify
           ref: ${{ inputs.deployment_ref }}
           desc: |
             Do you trust the author of this PR? Maybe this build will steal your keys or give you malware.
@@ -59,13 +59,9 @@ jobs:
 
       - name: Add redirects file
         # We fetch from github directly as we don't bother checking out the repo
-        # Not needed for storybook deployments
-        if: inputs.package != 'storybook'
         run: curl -s https://raw.githubusercontent.com/element-hq/element-call/main/config/netlify_redirects > webapp/_redirects
 
       - name: Add config file
-        # Not needed for storybook deployments
-        if: inputs.package != 'storybook'
         run: |
           if [ "${INPUTS_PACKAGE}" = "full" ]; then
             curl -s "https://raw.githubusercontent.com/${INPUTS_PR_HEAD_FULL_NAME}/${INPUTS_PR_HEAD_REF}/config/config_netlify_preview.json" > webapp/config.json
@@ -82,7 +78,7 @@ jobs:
         with:
           publish-dir: webapp
           deploy-message: "Deploy from GitHub Actions"
-          alias: ${{ inputs.package == 'sdk' && format('pr{0}-sdk', inputs.pr_number) || inputs.package == 'storybook' && format('pr{0}-storybook', inputs.pr_number) || format('pr{0}', inputs.pr_number) }}
+          alias: ${{ inputs.package == 'sdk' && format('pr{0}-sdk', inputs.pr_number) || format('pr{0}', inputs.pr_number) }}
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

.github/workflows/pr-deploy.yaml

@@ -14,7 +14,7 @@ jobs:
     # 2. Event must be a pull_request
     # 3. Head repository must be the SAME as the base repository (No Forks!)
     if: >
-      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.conclusion == 'success' && 
       github.event.workflow_run.event == 'pull_request' &&
       github.event.workflow_run.head_repository.full_name == github.repository
     runs-on: ubuntu-latest
@@ -63,24 +63,6 @@ jobs:
       NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
       NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
 
-  netlify-storybook:
-    needs: prdetails
-    if: ${{ needs.prdetails.outputs.pr_data_json && contains(fromJSON(needs.prdetails.outputs.pr_data_json).labels.*.name, 'storybook build') }}
-    permissions:
-      deployments: write
-    uses: ./.github/workflows/deploy-to-netlify.yaml
-    with:
-      artifact_run_id: ${{ github.event.workflow_run.id || github.run_id }}
-      pr_number: ${{ needs.prdetails.outputs.pr_number }}
-      pr_head_full_name: ${{ github.event.workflow_run.head_repository.full_name }}
-      pr_head_ref: ${{ needs.prdetails.outputs.pr_data_json && fromJSON(needs.prdetails.outputs.pr_data_json).head.ref }}
-      deployment_ref: ${{ needs.prdetails.outputs.pr_data_json && fromJSON(needs.prdetails.outputs.pr_data_json).head.sha || github.ref || github.head_ref }}
-      package: storybook
-    secrets:
-      ELEMENT_BOT_TOKEN: ${{ secrets.ELEMENT_BOT_TOKEN }}
-      NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
-      NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
-
   docker:
     if: ${{ needs.prdetails.outputs.pr_data_json && contains(fromJSON(needs.prdetails.outputs.pr_data_json).labels.*.name, 'docker build') }}
     needs: prdetails

CONTRIBUTING.md

@@ -1,3 +1,71 @@
 # Contributing code to Element
 
 Element follows the same pattern as the [matrix-js-sdk](https://github.com/matrix-org/matrix-js-sdk/blob/develop/CONTRIBUTING.md).
+
+# Contributing to Element Call
+
+Element Call is a native Matrix video conferencing application built on
+[MatrixRTC (MSC4143)](https://github.com/matrix-org/matrix-spec-proposals/pull/4143)
+and [LiveKit](https://livekit.io/). It runs in multiple deployment contexts — as a
+standalone web app and as a widget embedded in Element Web, Element X iOS, and
+Element X Android. It is also the primary R&D foundation for MatrixRTC, which means
+its architecture, maintainability, and flexibility are held to a high standard.
+
+We welcome contributions from the community. This document explains how to
+contribute effectively so that both you and the maintainers get the best outcome.
+
+## Issue First Policy
+
+> [!IMPORTANT]
+> Before writing a single line of code for a new feature or UI change, you **must**
+> open an issue and have the approach agreed with the maintainers.
+>
+> **We will not review or merge feature or UI pull requests that arrive without a
+> corresponding, pre-approved issue.**
+
+This is not gatekeeping — it's how we prevent wasted effort on both sides. Element
+Call must work correctly across multiple deployment contexts and meet specific product
+and design requirements. It is also a fast-moving codebase that underpins ongoing
+MatrixRTC development. A PR that looks reasonable in isolation can easily conflict
+with in-progress work, planned architecture changes, or design decisions that haven't
+been publicly documented yet.
+
+The issue is where we resolve all of that **before** anyone writes code.
+
+**Bug fixes** are no exception — most confirmed bugs should already have an issue anyways, existing issues that are marked as bugs have an implicit maintainer approval. If the solution for the bug is controversial it is highly recommended to discuss the approach in the issue before opening a PR.
+
+## Contribution Workflow
+
+1. **Open an issue** using the [Enhancement request](https://github.com/element-hq/element-call/issues/new?template=enhancement.yml) template.
+2. **Wait for feedback.** A maintainer will comment on the issue **within two weeks**. The use case and approach will get dicussed.
+   This may involve questions, suggestions, or a request to adjust scope.
+   This also allows to bring design and product into the loop before code gets created.
+3. **Get a green light.** Wait for explicit approval from a maintainer before starting
+   implementation.
+4. **Implement.** Write the code against the agreed approach.
+5. **Open a PR.** Link to the issue in your PR description and satisfy the checklist
+   in the PR template.
+
+## Code Quality
+
+Element Call moves fast and the codebase must stay clean and maintainable.
+
+- **Take responsibility for AI-generated code.** AI tools can be a useful aid, but we expect all the generated code to be understood and reasoned about by the contributor. Questions by the maintainers should be answered without just forwarding them to AI. The maintainers also have access to AI tools. If your contribution is just transporting messages between LLM <-> maintaines all our time is better used if the maintainers decide to interact with AI for this specific problem by themselves.
+- **Think across deployment contexts.** Changes must work correctly in both standalone
+  and widget modes. Consider how your change interacts with Element Web, Element X
+  iOS, and Element X Android.
+- **Write tests.** New functionality should be covered by tests. Where it is feasible,
+  existing uncovered code touched by your PR should also gain tests.
+
+## Contributor License Agreement
+
+All contributors must sign the
+[Element Contributor License Agreement](https://cla-assistant.io/element-hq/element-call)
+before their contribution can be merged. The CLA assistant bot will prompt you
+automatically when you open a PR.
+
+## Getting Help
+
+The best place to ask questions about Element Call development is the MatrixRTC room:
+
+**[#matrixRtc:matrix.org](https://matrix.to/#/#matrixrtc:matrix.org)**