diff --git a/docs/add_threePids.md b/docs/add_threePids.md index 6fb0aff426..8d02702ca6 100644 --- a/docs/add_threePids.md +++ b/docs/add_threePids.md @@ -1,5 +1,34 @@ # Adding and removing ThreePids to an account + + +* [Add email](#add-email) + * [User enter the email](#user-enter-the-email) + * [The email is already added to an account](#the-email-is-already-added-to-an-account) + * [The email is free](#the-email-is-free) +* [User receives an e-mail](#user-receives-an-e-mail) + * [User clicks on the link](#user-clicks-on-the-link) + * [User returns on Element](#user-returns-on-element) + * [User enters his password](#user-enters-his-password) + * [The link has not been clicked](#the-link-has-not-been-clicked) + * [Wrong password](#wrong-password) + * [The link has been clicked and the account password is correct](#the-link-has-been-clicked-and-the-account-password-is-correct) +* [Remove email](#remove-email) + * [User want to remove an email from his account](#user-want-to-remove-an-email-from-his-account) + * [Email was not bound to an identity server](#email-was-not-bound-to-an-identity-server) + * [Email was bound to an identity server](#email-was-bound-to-an-identity-server) +* [Add phone number](#add-phone-number) + * [The phone number is already added to an account](#the-phone-number-is-already-added-to-an-account) + * [The phone number is free](#the-phone-number-is-free) +* [User receive a text message](#user-receive-a-text-message) + * [User enter the code to the app](#user-enter-the-code-to-the-app) + * [Wrong code](#wrong-code) + * [Correct code](#correct-code) +* [Remove phone number](#remove-phone-number) + * [User wants to remove a phone number from his account](#user-wants-to-remove-a-phone-number-from-his-account) + + + ## Add email ### User enter the email diff --git a/docs/analytics.md b/docs/analytics.md index 135ace81b0..9b2c176912 100644 --- a/docs/analytics.md +++ b/docs/analytics.md @@ -1,5 +1,13 @@ # Analytics in Element + + +* [Solution](#solution) +* [How to add a new Event](#how-to-add-a-new-event) +* [Forks of Element](#forks-of-element) + + + ## Solution Element is using PostHog to send analytics event. diff --git a/docs/color_migration_guide.md b/docs/color_migration_guide.md index 31a531d124..f83a88e2b2 100644 --- a/docs/color_migration_guide.md +++ b/docs/color_migration_guide.md @@ -1,5 +1,14 @@ # Color migration + + + * [Changes](#changes) + * [Main change for developers](#main-change-for-developers) + * [Remaining work](#remaining-work) + * [Migration guide](#migration-guide) + + + ### Changes - use colors defined in https://www.figma.com/file/X4XTH9iS2KGJ2wFKDqkyed/Compound?node-id=557%3A0 diff --git a/docs/design.md b/docs/design.md index a79f19cf3e..f390725560 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,5 +1,31 @@ # Element Android design + + +* [Introduction](#introduction) +* [How to import from Figma to the Element Android project](#how-to-import-from-figma-to-the-element-android-project) + * [Colors](#colors) + * [Text](#text) + * [Dimension, position and margin](#dimension-position-and-margin) + * [Icons](#icons) + * [Export drawable from Figma](#export-drawable-from-figma) + * [Import in Android Studio](#import-in-android-studio) + * [Images](#images) +* [Figma links](#figma-links) + * [Coumpound](#coumpound) + * [Login](#login) + * [Login v2](#login-v2) + * [Room list](#room-list) + * [Timeline](#timeline) + * [Voice message](#voice-message) + * [Room settings](#room-settings) + * [VoIP](#voip) + * [Presence](#presence) + * [Spaces](#spaces) + * [List to be continued...](#list-to-be-continued) + + + ## Introduction Design at element.io is done using Figma - https://www.figma.com diff --git a/docs/identity_server.md b/docs/identity_server.md index e765ae3949..a1ee86cb19 100644 --- a/docs/identity_server.md +++ b/docs/identity_server.md @@ -1,5 +1,19 @@ # Identity server + + +* [Introduction](#introduction) +* [Implementation](#implementation) +* [Related MSCs](#related-mscs) +* [Steps and requirements](#steps-and-requirements) +* [Screens](#screens) + * [Settings](#settings) + * [Discovery screen](#discovery-screen) + * [Set identity server screen](#set-identity-server-screen) +* [Ref:](#ref:) + + + Issue: #607 PR: #1354 diff --git a/docs/integration_tests.md b/docs/integration_tests.md index e79f966d1f..b5a830e7ff 100644 --- a/docs/integration_tests.md +++ b/docs/integration_tests.md @@ -1,5 +1,18 @@ # Integration tests + + +* [Pre requirements](#pre-requirements) +* [Install and run Synapse](#install-and-run-synapse) +* [Run the test](#run-the-test) +* [Stop Synapse](#stop-synapse) +* [Troubleshoot](#troubleshoot) + * [Android Emulator does cannot reach the homeserver](#android-emulator-does-cannot-reach-the-homeserver) + * [Tests partially run but some fail with "Unable to contact localhost:8080"](#tests-partially-run-but-some-fail-with-"unable-to-contact-localhost:8080") + * [virtualenv command fails](#virtualenv-command-fails) + + + Integration tests are useful to ensure that the code works well for any use cases. They can also be used as sample on how to use the Matrix SDK. diff --git a/docs/jitsi.md b/docs/jitsi.md index 1b4e0a37b4..4dd06effdb 100644 --- a/docs/jitsi.md +++ b/docs/jitsi.md @@ -1,20 +1,32 @@ # Jitsi in Element Android + + +* [Native Jitsi SDK](#native-jitsi-sdk) + * [How to build the Jitsi Meet SDK](#how-to-build-the-jitsi-meet-sdk) + * [Jitsi version](#jitsi-version) + * [Run the build script](#run-the-build-script) + * [Link with the new generated library](#link-with-the-new-generated-library) + * [Sanity tests](#sanity-tests) + * [Export the build library](#export-the-build-library) + + + Native Jitsi support has been added to Element Android by the PR [#1914](https://github.com/vector-im/element-android/pull/1914). The description of the PR contains some documentation about the behaviour in each possible room configuration. Also, ensure to have a look on [the documentation from Element Web](https://github.com/vector-im/element-web/blob/develop/docs/jitsi.md) The official documentation about how to integrate the Jitsi SDK in an Android app is available here: https://jitsi.github.io/handbook/docs/dev-guide/dev-guide-android-sdk. -# Native Jitsi SDK +## Native Jitsi SDK The Jitsi SDK is built by ourselves with the flag LIBRE_BUILD, to be able to be integrated on the F-Droid version of Element Android. The generated maven repository is then host in the project https://github.com/vector-im/jitsi_libre_maven -## How to build the Jitsi Meet SDK +### How to build the Jitsi Meet SDK -### Jitsi version +#### Jitsi version Update the script `./tools/jitsi/build_jisti_libs.sh` with the tag of the project `https://github.com/jitsi/jitsi-meet`. @@ -22,7 +34,7 @@ Latest tag can be found from this page: https://github.com/jitsi/jitsi-meet-rele Currently we are building the version with the tag `android-sdk-3.10.0`. -### Run the build script +#### Run the build script At the root of the Element Android, run the following script: @@ -32,7 +44,7 @@ At the root of the Element Android, run the following script: It will build the Jitsi Meet Android library and put every generated files in the folder `/tmp/jitsi` -### Link with the new generated library +#### Link with the new generated library - Update the file `./build.gradle` to use the previously created local Maven repository. Currently we have this line: @@ -57,7 +69,7 @@ implementation('com.facebook.react:react-native-webrtc:1.92.1-jitsi-9093212@aar' - Perform a gradle sync and build the project - Perform test -### Sanity tests +#### Sanity tests In order to validate that the upgrade of the Jitsi and WebRTC dependency does not break anything, the following sanity tests have to be performed, using two devices: - Make 1-1 audio call (so using WebRTC) @@ -65,7 +77,7 @@ In order to validate that the upgrade of the Jitsi and WebRTC dependency does no - Create and join a conference call with audio only (so using Jitsi library). Leave the conference. Join it again. - Create and join a conference call with audio and video (so using Jitsi library) Leave the conference. Join it again. -### Export the build library +#### Export the build library If all the tests are passed, you can export the generated Jitsi library to our Maven repository. @@ -81,4 +93,4 @@ url "https://github.com/vector-im/jitsi_libre_maven/raw/master/android-sdk-3.10. - Build the project and perform the sanity tests again. -- Update the file `/CHANGES.md` to notify about the library upgrade, and create a regular PR for project Element Android. \ No newline at end of file +- Update the file `/CHANGES.md` to notify about the library upgrade, and create a regular PR for project Element Android. diff --git a/docs/notifications.md b/docs/notifications.md index 601b64322a..612b8785b8 100644 --- a/docs/notifications.md +++ b/docs/notifications.md @@ -1,28 +1,33 @@ This document aims to describe how Element android displays notifications to the end user. It also clarifies notifications and background settings in the app. # Table of Contents -1. [Prerequisites Knowledge](#prerequisites-knowledge) - * [How does a matrix client get a message from a homeserver?](#how-does-a-matrix-client-get-a-message-from-a-homeserver) - * [How does a mobile app receives push notification?](#how-does-a-mobile-app-receives-push-notification) - * [Push VS Notification](#push-vs-notification) - * [Push in the matrix federated world](#push-in-the-matrix-federated-world) - * [How does the homeserver know when to notify a client?](#how-does-the-homeserver-know-when-to-notify-a-client) - * [Push vs privacy, and mitigation](#push-vs-privacy-and-mitigation) - * [Background processing limitations](#background-processing-limitations) -2. [Element Notification implementations](#element-notification-implementations) - * [Requirements](#requirements) - * [Foreground sync mode (Gplay & F-Droid)](#foreground-sync-mode-gplay--f-droid) - * [Push (FCM) received in background](#push-fcm-received-in-background) - * [FCM Fallback mode](#fcm-fallback-mode) - * [F-Droid background Mode](#f-droid-background-mode) -3. [Application Settings](#application-settings) + + + +* [Prerequisites Knowledge](#prerequisites-knowledge) + * [How does a matrix client get a message from a homeserver?](#how-does-a-matrix-client-get-a-message-from-a-homeserver?) + * [How does a mobile app receives push notification](#how-does-a-mobile-app-receives-push-notification) + * [Push VS Notification](#push-vs-notification) + * [Push in the matrix federated world](#push-in-the-matrix-federated-world) + * [How does the homeserver know when to notify a client?](#how-does-the-homeserver-know-when-to-notify-a-client?) + * [Push vs privacy, and mitigation](#push-vs-privacy-and-mitigation) + * [Background processing limitations](#background-processing-limitations) +* [Element Notification implementations](#element-notification-implementations) + * [Requirements](#requirements) + * [Foreground sync mode (Gplay and F-Droid)](#foreground-sync-mode-gplay-and-f-droid) + * [Push (FCM) received in background](#push-fcm-received-in-background) + * [FCM Fallback mode](#fcm-fallback-mode) + * [F-Droid background Mode](#f-droid-background-mode) +* [Application Settings](#application-settings) + + First let's start with some prerequisite knowledge -# Prerequisites Knowledge +## Prerequisites Knowledge -## How does a matrix client get a message from a homeserver? +### How does a matrix client get a message from a homeserver? In order to get messages from a homeserver, a matrix client need to perform a ``sync`` operation. @@ -52,7 +57,7 @@ By default, this is 0, so the server will return immediately even if the respons When the Element Android app is open (i.e in foreground state), the default timeout is 30 seconds, and delay is 0. -## How does a mobile app receives push notification +### How does a mobile app receives push notification Push notification is used as a way to wake up a mobile application when some important information is available and should be processed. @@ -69,7 +74,7 @@ De-Googlified devices need to rely on something else in order to stay up to date There some cases when devices with google services cannot use FCM (network infrastructure limitations -firewalls-, privacy and or independence requirement, source code licence) -## Push VS Notification +### Push VS Notification This need some disambiguation, because it is the source of common confusion: @@ -81,7 +86,7 @@ This need some disambiguation, because it is the source of common confusion: Notifications are not always triggered by a push (One can display a notification locally triggered by an alarm) -## Push in the matrix federated world +### Push in the matrix federated world In order to send a push to a mobile, App developers need to have a server that will use the FCM APIs, and these APIs requires authentication! This server is called a **Push Gateway** in the matrix world @@ -122,7 +127,7 @@ Recommended reading: * https://matrix.org/docs/spec/client_server/r0.4.0.html#id128 -## How does the homeserver know when to notify a client? +### How does the homeserver know when to notify a client? This is defined by [**push rules**](https://matrix.org/docs/spec/client_server/r0.4.0.html#push-rules-). @@ -140,14 +145,14 @@ Of course, content patterns matching cannot be used for encrypted messages serve That is why clients are able to **process the push rules client side** to decide what kind of notification should be presented for a given event. -## Push vs privacy, and mitigation +### Push vs privacy, and mitigation As seen previously, App developers don't directly send a push to the end user's device, they use a Push Provider as intermediary. So technically this intermediary is able to read the content of what is sent. App developers usually mitigate this by sending a `silent notification`, that is a notification with no identifiable data, or with an encrypted payload. When the push is received the app can then synchronise to it's server in order to generate a local notification. -## Background processing limitations +### Background processing limitations A mobile applications process live in a managed word, meaning that its process can be limited (e.g no network access), stopped or killed at almost anytime by the Operating System. @@ -167,15 +172,15 @@ The documentation on this subject is vague, and as per our experiments not alway It is getting more and more complex to have reliable notifications when FCM is not used. -# Element Notification implementations +## Element Notification implementations -## Requirements +### Requirements Element Android must work with and without FCM. * The Element android app published on F-Droid do not rely on FCM (all related dependencies are not present) * The Element android app published on google play rely on FCM, with a fallback mode when FCM registration has failed (e.g outdated or missing Google Play Services) -## Foreground sync mode (Gplay & F-Droid) +### Foreground sync mode (Gplay and F-Droid) When in foreground, Element performs sync continuously with a timeout value set to 10 seconds (see HttpPooling). @@ -185,7 +190,7 @@ This mode is turned on when the app enters foreground, and off when enters backg In background, and depending on whether push is available or not, Element will use different methods to perform the syncs (Workers / Alarms / Service) -## Push (FCM) received in background +### Push (FCM) received in background In order to enable Push, Element must first get a push token from the firebase SDK, then register a pusher with this token on the homeserver. @@ -225,7 +230,7 @@ Upon reception of the FCM push, Element will perform a sync call to the homeserv Element implements several strategies in these cases (TODO document) -## FCM Fallback mode +### FCM Fallback mode It is possible that Element is not able to get a FCM push token. Common errors (among several others) that can cause that: @@ -246,7 +251,7 @@ Usually in this mode, what happen is when you take back your phone in your hand, The fallback mode is supposed to be a temporary state waiting for the user to fix issues for FCM, or for App Developers that has done a fork to correctly configure their FCM settings. -## F-Droid background Mode +### F-Droid background Mode The F-Droid Element flavor has no dependencies to FCM, therefore cannot relies on Push. @@ -266,9 +271,7 @@ That is why on Element F-Droid, the broadcast receiver will acquire a temporary Note that foreground services require to put a notification informing the user that the app is doing something even if not launched). - - -# Application Settings +## Application Settings **Notifications > Enable notifications for this account** diff --git a/docs/pull_request.md b/docs/pull_request.md index 94f8f3b6d8..d2d2bb7a3b 100644 --- a/docs/pull_request.md +++ b/docs/pull_request.md @@ -1,5 +1,43 @@ # Pull requests + + +* [Introduction](#introduction) +* [Who should read this document?](#who-should-read-this-document?) +* [Submitting PR](#submitting-pr) + * [Who can submit pull requests?](#who-can-submit-pull-requests?) + * [Humans](#humans) + * [Draft PR?](#draft-pr?) + * [Base branch](#base-branch) + * [PR Review Assignment](#pr-review-assignment) + * [PR review time](#pr-review-time) + * [Re-request PR review](#re-request-pr-review) + * [When create split PR?](#when-create-split-pr?) + * [Avoid fixing other unrelated issue in a big PR](#avoid-fixing-other-unrelated-issue-in-a-big-pr) + * [Bots](#bots) + * [Dependabot](#dependabot) + * [Gradle wrapper](#gradle-wrapper) + * [Sync analytics plan](#sync-analytics-plan) +* [Reviewing PR](#reviewing-pr) + * [Who can review pull requests?](#who-can-review-pull-requests?) + * [What to have in mind when reviewing a PR](#what-to-have-in-mind-when-reviewing-a-pr) + * [Rules](#rules) + * [Check the form](#check-the-form) + * [PR title](#pr-title) + * [PR description](#pr-description) + * [File change](#file-change) + * [Check the commit](#check-the-commit) + * [Check the substance](#check-the-substance) + * [Make a dedicated meeting to review the PR](#make-a-dedicated-meeting-to-review-the-pr) + * [What happen to the issue(s)?](#what-happen-to-the-issues?) + * [Merge conflict](#merge-conflict) + * [When and who can merge PR](#when-and-who-can-merge-pr) + * [Merge type](#merge-type) + * [Resolve conversation](#resolve-conversation) +* [Responsibility](#responsibility) + + + ## Introduction This document gives some clue about how to efficiently manage Pull Requests (PR). This document is a first draft and may be improved later. diff --git a/docs/signin.md b/docs/signin.md index 0a234d2a20..65e305389f 100644 --- a/docs/signin.md +++ b/docs/signin.md @@ -2,6 +2,27 @@ This document describes the flow of signin to a homeserver, and also the flow when user want to reset his password. Examples come from the `matrix.org` homeserver. + + +* [Sign in flows](#sign-in-flows) + * [Get the flow](#get-the-flow) + * [Login with username](#login-with-username) + * [Incorrect password](#incorrect-password) + * [Correct password:](#correct-password:) + * [Login with email](#login-with-email) + * [Unknown email](#unknown-email) + * [Known email, wrong password](#known-email-wrong-password) + * [Known email, correct password](#known-email-correct-password) + * [Login with Msisdn](#login-with-msisdn) + * [Login with SSO](#login-with-sso) +* [Reset password](#reset-password) + * [Send email](#send-email) + * [When the email is not known](#when-the-email-is-not-known) + * [When the email is known](#when-the-email-is-known) + * [User clicks on the link](#user-clicks-on-the-link) + + + ## Sign in flows ### Get the flow @@ -322,4 +343,4 @@ curl -X POST --data $'{"auth":{"type":"m.login.email.identity","threepid_creds": {} ``` -The password has been changed, and all the existing token are invalidated. User can now login with the new password. \ No newline at end of file +The password has been changed, and all the existing token are invalidated. User can now login with the new password. diff --git a/docs/signup.md b/docs/signup.md index 97cd20a423..0b01338965 100644 --- a/docs/signup.md +++ b/docs/signup.md @@ -4,6 +4,20 @@ This document describes the flow of registration to a homeserver. Examples come *Ref*: https://matrix.org/docs/spec/client_server/latest#account-registration-and-management + + +* [Sign up flows](#sign-up-flows) + * [First step](#first-step) + * [Step 1: entering user name and password](#step-1:-entering-user-name-and-password) + * [If username already exists](#if-username-already-exists) + * [Step 2: entering email](#step-2:-entering-email) + * [Step 2 bis: user enters an email](#step-2-bis:-user-enters-an-email) + * [Step 3: Accepting T&C](#step-3:-accepting-t&c) + * [Step 4: Captcha](#step-4:-captcha) + * [Step 5: MSISDN](#step-5:-msisdn) + + + ## Sign up flows ### First step diff --git a/docs/ui-tests.md b/docs/ui-tests.md index 667a6ed7fb..d0b9db6818 100644 --- a/docs/ui-tests.md +++ b/docs/ui-tests.md @@ -10,6 +10,20 @@ Currently the test are covering a small set of application flows: - Self verification via emoji - Self verification via passphrase + + +* [Prerequisites:](#prerequisites:) +* [Run the tests](#run-the-tests) + * [From the source code](#from-the-source-code) + * [From command line](#from-command-line) +* [Recipes](#recipes) + * [Wait for initial sync](#wait-for-initial-sync) + * [Accessing current activity](#accessing-current-activity) + * [Interact with other session](#interact-with-other-session) + * [Contributing to the UiAllScreensSanityTest](#contributing-to-the-uiallscreenssanitytest) + + + ## Prerequisites: Out of the box, the tests use one of the homeservers (located at http://localhost:8080) of the "Demo Federation of Homeservers" (https://github.com/matrix-org/synapse#running-a-demo-federation-of-synapses).