Support can be found in 
To make a great product with a great user experience, all the small efforts need to go in the same direction and be aligned and consistent with each other.
Before making your contribution, please consider the following:
- One product can’t do everything well. Element is focusing on private end-to-end encrypted messaging and voice - this can either be for consumers (e.g. friends and family) or for professional teams and organizations. Public forums and other types of chats without E2EE remain supported but are not the primary use case in case UX compromises need to be made.
- There are 3 platforms - iOS, Android and Web/Desktop. These platforms need to have feature parity and design consistency. For some features, supporting all platforms is a must have, in some cases exceptions can be made to have it on one platform only.
- To make sure your idea fits both from a design/solution and use case perspective, please open a new issue (or find an existing issue) in element-meta repository describing the use case and how you plan to tackle it. Do not just describe what feature is missing, explain why the users need it with a couple of real life examples from the field.
- In case of an existing issue, please comment that you're planning to contribute. If you create a new issue, please specify that in the issue. In such a case we will try to review the issue ASAP and provide you with initial feedback so you can be confident if and at which conditions your contributions will be accepted.
Once we know that you want to contribute and have confirmed that the new feature is overall aligned with the product direction, the designers of the core team will help you with the designs and any other type of guidance when it comes to the user experience. We will try to unblock you as quickly as we can, but it may not be instant. Having a clear understanding of the use case and the impact of the feature will help us with the prioritization and faster responses.
Only once all of the above is met should you open a PR with your proposed changes.
It's mandatory to have homebrew installed on your mac, and run after the checkout:
swift run tools setup-project
This will:
- Install various brew dependencies required for the project (like xcodegen).
- Set up git to use the shared githooks from the repo, instead of the default ones.
- Automatically run xcodegen for the first time.
We suggest using an Xcode version later than 15.0.1.
The Xcode project can be directly compiled through the shared Element X scheme which includes the main application as well as the unit and UI tests.
The Xcode project itself is generated through xcodegen so any changes shouldn't be made directly to it but to the configuration files.
Dependencies will be automatically fetched through the Swift Package Manager, including a release version of the MatrixRustSDK. If you encounter issues while resolving the package graph please attempt a cache reset through File -> Packages -> Reset Package Caches.
To setup the RustSDK in local development mode run the following command
swift run tools build-sdk
This will clone a copy of the SDK if needed, build it for all supported architectures and configure Element X to use the built framework. To learn about additional options run
swift run tools build-sdk --help
The project depends on some tools for the build process which are normally installed through swift run tools setup-project. Installing them manually though is as easy as copying what the script does
brew install [...]
Git LFS is used to store UI and Preview test snapshots. swift run tools setup-project will already install it, however it can also be installed after a checkout by running:
git lfs install
If you make changes to the UI you may cause existing UI and Preview test snapshots to fail. The UITests run user flows and record snapshots while doing so using the settings defined under checkEnvironments while the PreviewTests use the settings defined in PreviewTests.swift. The snapshots are stored under Sources/__Snapshots__ in their respective target's folder.
The project uses its own shared githooks stored in the .githooks folder, you will need to configure git to use such folder, this is already done if you have run the setup tool with swift run tools setup-project otherwise you would need to run:
git config core.hooksPath .githooks
The project uses Localazy and is sharing its translations with the Element X Android project: https://localazy.com/p/element
Please read the Android docs for more information about how this works. Note: On iOS we don't have the additional step of filtering strings per module.
Please do not manually edit the Localizable.strings, Localizable.stringsdict or InfoPlist.strings files! If your PR requires new strings to be added, add the en values to Untranslated.strings/Untranslated.stringsdict and one of the team will transfer them over to Localazy for you.
Once the strings have been added to Localazy, they can be downloaded by running swift run tools download-strings.
Element X uses a suite of Swift command line tools for running actions on the CI and tries to keep the configuration confined to Tools/Sources alongside the project's xcodegen configuration.
Please run swift run tools ci --help to see available options.
Note: We are in the process of converting our Fastlane lanes to Swift and so long-term are intending to remove Fastlane from the project all together.
It's possible to debug the app's network traffic with a proxy server by setting the HTTPS_PROXY environment variable in the Element X scheme to the proxy's address (e.g. localhost:8080 for mitmproxy).
Please see our pull request guide.
New screen flows are currently using the MVVM-Coordinator pattern. Please refer to the create screen template section.
Our changelog is automatically generated by GitHub, based on the PR title that you use when opening the issue. The changelog can be categorised by applying one of the pr- labels to your PR. The mapping of Label → Section can be found in the release.yml file. The contribution will be automatically credited to your GitHub username.
For Swift coding style we use SwiftLint to check some conventions at compile time (rules are located in the .swiftlint.yml file).
Otherwise please have a look to Apple Swift conventions. We are also using some of the conventions of raywenderlich.com Swift style guide.
We enforce the coding style by running checks on the CI for every PR through Danger, SwiftLint, SwiftFormat and SonarCloud
We also gather coverage reports on every PR through Codecov and will eventually start enforcing minimums.
Thank your for contributing to Matrix projects!