mirror of https://github.com/Novaloop-AG/element-x-ios.git synced 2026-10-31 08:15:24 +00:00

Files

T

Mauro b1ed870474 Support for Xcode 27 on CI (#6217 )

* Run the tests on iOS 27.0

Bump the required simulator OS in the preview, UI and Compound tests, and the CI tool's default OS, from 26.5 to 27.0. Test devices stay the same.

iOS 27 writes transcoded videos 146 bytes larger, so update the expected sizes in MediaUploadingPreprocessorTests.

* Build and test on CI with Xcode 27

Select Xcode 27 in ci_common.sh and move every macOS workflow to the xcode-27 runner image, as macos-26 doesn't include Xcode 27. The Compound workflow now also creates its simulator on the iOS 27.0 runtime.

The xcode-27 runners are slower, so give the unit, Enterprise, Compound and snapshot recording jobs longer timeouts.

* Fix the preview snapshot layout on iOS 27

On iOS 27 the hosting controller applies the window's safe area when rendering, but the snapshot size comes from sizeThatFits, which ignores it. Component previews were shifted down and clipped at the bottom. Disable the hosting controller's safe area regions for these snapshots so the measured and rendered layouts match.

swift-snapshot-testing also renders into a window without a scene, and on iOS 27 a navigation stack in such a window reserves space for a large title it never shows, leaving a gap below the navigation bar. Attach the render window to the app's scene until swift-snapshot-testing handles it.

The invite users and add rooms screens sized their selected items row from a measured width stored in state, which is zero on the first layout pass, so snapshots could draw the row empty. Use containerRelativeFrame instead. The add rooms search previews now also wait for their results, and the search previews that show a clear button get a small precision tolerance, as it renders inconsistently in snapshots.

* Re-record the preview snapshots on iOS 27.0

Recorded on an iPhone SE (3rd generation) simulator running iOS 27.0 with Xcode 27.0 (27A266a). The changes come from iOS 27 rendering: text anti-aliasing, hyphenation and line breaking, navigation bars and toggles that now render in snapshots, lazy stacks that were blank on iOS 26, and pseudo-language locale formatting.

* Fix the UI tests on iOS 27

iOS 27 no longer exposes accessibility identifiers on SwiftUI menu items, so the space exploration test now finds them by label within the menu. On iPad, the start chat search field keeps focus after submitting and can swallow the next tap, so retry the tap if the create room screen doesn't appear.

* Re-record the UI test snapshots on iOS 27.0

Recorded on iPhone 17 and iPad (A16) simulators running iOS 27.0 with Xcode 27.0. The changes come from iOS 27 styling, like the keyboard height and glass borders. This also removes the iPad app lock setup snapshots, which have been orphaned since those tests stopped running on iPad.

* Fix the accessibility tests crashing on iOS 27

The accessibility tests' previews wrapper kept its ImageRenderer alive across the awaits that follow the render. On iOS 27, releasing it at that point tears down its view graph outside of a SwiftUI update, which hits an assertion and crashes the app. Release the renderer as soon as the image has been rendered.

* Keep the accessibility tests' image renderers alive on iOS 27

Releasing the ImageRenderer straight away wasn't enough: on iOS 27, releasing one that rendered a preview crashes SwiftUI whichever context it happens in. Keep the renderers alive instead. Each test launches a fresh app, so they only live for the one test.

* Share the UI tests' app settings with their mock user session

Since the user session flow reads its settings from UserSettings, the UI tests' mock user session was wrapping a fresh volatile AppSettings instead of the one the tests configure. The flags that skip onboarding weren't picked up, so every user session UI test got stuck on the notifications permission screen.

* Re-record the Compound snapshots on iOS 27.0

Apply the same safe area fix as the app's preview tests, so size-that-fits snapshots aren't clipped on iOS 27, and re-record the snapshots on an iPhone SE (3rd generation) simulator running iOS 27.0 in English (US).

* Fix a race reading the keyboard in the accessibility tests

On iOS 27 the QR code login screen's keyboard can be dismissing between checking that it exists and reading its frame, which fails the test. Snapshot it in a single query instead.

2026-09-29 17:02:48 +02:00

11 KiB

Raw Permalink Blame History

Contributing to Element X iOS

Support can be found in .

Adding a new feature or enhancement

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.

Etiquette

As stated above all significant changes should be communicated through an issue before opening a PR
We are happy to receive contributions but features always require maintenance, so depending on the change we might not be willing to accept it
We are also fine with AI led contributions within reasonable bounds
- You are completely responsible for the quality of the PR
- If the PR doesn't show minimal effort (code does not compile, code does not work as expected, etc.) on your part it will be closed
- Please write the description yourself, we don't have the bandwidth to read LLM essays. The code needs to speak for itself.
We use git for version control and GitHub for reviews, so in order to make everybody's life easier please:
- Keep the existing pull request template
- Don't submit large PRs, especially if not previously talked about. Anything above 200 lines is large (excluding generated code e.g. tests, translations, mocks)
- Please don't open unfinished PRs and expect us to fill in the details
- If you would like our opinion/direction on unfinished code please link your branch or idea in the ticket
- Please limit the number of commits in a single PR. We are perfectly happy with splitting work across multiple sessions as long as they're logically independent and show promise of progress (ideally expressed through a ticket)
- Each and every commit should stand on its own, clearly explaining what it does and why
Once a PR goes into review please don't rewrite the history unless agreed so with the reviewer.
- Tweaks and fixes following review can be directly committed (to be interactively rebased later) or as fixups

The reviewer's response time will generally match yours. Switching contexts is very hard so please act accordingly. You are responsible for making the reviewers job enjoyable!

Setting up a development environment

Setup Project

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.

Xcode

We suggest always using the Xcode version specified by xcode_select_for_github_actions in ci_common.sh.

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

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

Tools

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

Snapshot Tests

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.

To run the preview tests:

Use an iPhone SE (3rd generation) simulator running iOS 27.0.
On that simulator, go to Settings -> General -> Language & Region and select United States as the region, with English (US) as the only preferred language. This is a one time setup, as long as you keep using the same simulator.
Select the PreviewTests scheme and run the tests.

Newly created screens will automatically have their screenshots added based off their TestablePreview Swift previews. If you are modifying an existing screen, you will first need to delete the old snapshots for that screen before running the tests. Alternatively, if you enable RECORD_FAILURES in the preview test plans's environment variables (PreviewTests/SupportingFiles/Previewtests.xctestplan), it will overwrite snapshot failures with the updated screenshot.

Githooks

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

Strings and Translations

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.

Continuous Integration

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.

Network debugging proxy

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).

Pull requests

Please see our pull request guide.

Implementing a new screen

New screen flows are currently using the MVVM-Coordinator pattern. Please refer to the create screen template section.

Changelog

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.

Coding style

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 PR Checks, SwiftLint, SwiftFormat and SonarCloud

We also gather coverage reports on every PR through Codecov and will eventually start enforcing minimums.

Thanks

Thank your for contributing to Matrix projects!

11 KiB Raw Permalink Blame History Unescape Escape