diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f0191d43e0..0126d89a9c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,16 +2,16 @@ -* [Developer onboarding](#developer-onboarding) -* [Contributing code to Matrix](#contributing-code-to-matrix) -* [Android Studio settings](#android-studio-settings) -* [Compilation](#compilation) -* [Strings](#strings) - * [I want to add new strings to the project](#i-want-to-add-new-strings-to-the-project) +* [Contributing to Element](#contributing-to-element) * [I want to help translating Element](#i-want-to-help-translating-element) + * [I want to fix a bug](#i-want-to-fix-a-bug) + * [I want to add a new feature or enhancement](#i-want-to-add-a-new-feature-or-enhancement) +* [Developer onboarding](#developer-onboarding) + * [Submitting the PRs](#submitting-the-prs) + * [Android Studio settings](#android-studio-settings) + * [Compilation](#compilation) + * [Strings](#strings) * [Element X Android Gallery](#element-x-android-gallery) -* [I want to add a new feature to Element X Android](#i-want-to-add-a-new-feature-to-element-x-android) -* [I want to submit a PR to fix an issue](#i-want-to-submit-a-pr-to-fix-an-issue) * [Kotlin](#kotlin) * [Changelog](#changelog) * [Code quality](#code-quality) @@ -29,69 +29,67 @@ -## Developer onboarding - -For a detailed overview of the project, see [Developer Onboarding](./docs/_developer_onboarding.md). - -## Contributing code to Matrix - -If instead of contributing to the Element X Android project, you want to contribute to Synapse, the homeserver implementation, please read the [Synapse contribution guide](https://element-hq.github.io/synapse/latest/development/contributing_guide.html). +## Contributing to Element Element X Android support can be found in this room: [![Element X Android Matrix room #element-x-android:matrix.org](https://img.shields.io/matrix/element-x-android:matrix.org.svg?label=%23element-x-android:matrix.org&logo=matrix&server_fqdn=matrix.org)](https://matrix.to/#/#element-x-android:matrix.org). The rest of the document contains specific rules for Matrix Android projects. -## Android Studio settings - -Please set the "hard wrap" setting of Android Studio to 160 chars, this is the setting we use internally to format the source code (Menu `Settings/Editor/Code Style` then `Hard wrap at`). -Please ensure that you're using the project formatting rules (which are in the project at .idea/codeStyles/), and format the file before committing them. - -## Compilation - -This project should compile without any special action. Just clone it and open it with Android Studio, or compile from command line using `gradlew`. - -## Strings - -The strings of the project are managed externally using [https://localazy.com](https://localazy.com) and shared with Element X iOS. - -### I want to add new strings to the project - -Only the core team can modify or add English strings to Localazy. As an external contributor, if you want to add new strings, feel free to add an Android resource file to the project (for instance a file named `temporary.xml`), with a note in the description of the PR for the reviewer to integrate the String into `Localazy`. If accepted, the reviewer will add the String(s) for you, and then you can download them on your branch (following these [instructions](./tools/localazy/README.md#download-translations)) and remove the temporary file. - -Please follow the naming rules for the key. More details in [the dedicated section in this README.md](./tools/localazy/README.md#key-naming-rules) - ### I want to help translating Element To help translating, please go to [https://localazy.com/p/element](https://localazy.com/p/element). -- If you want to fix an issue with an English string, please open an issue on the github project of Element X (Android or iOS). Only the core team can modify or add English strings. - If you want to fix an issue in other languages, or add a missing translation, or even add a new language, please go to [https://localazy.com/p/element](https://localazy.com/p/element). - -More information can be found [in this README.md](./tools/localazy/README.md). +- If you want to fix an issue with an English string, please open an issue on the github project of Element X (Android or iOS). Only the core team can modify or add English strings. As an external contributor, if you want to add new strings, feel free to add an Android resource file to the project (for instance a file named `temporary.xml`), with a note in the description of the PR for the reviewer to integrate the String into `Localazy`. If accepted, the reviewer will add the String(s) for you, and then you can download them on your branch (following these [instructions](./tools/localazy/README.md#download-translations)) and remove the temporary file. Please follow the naming rules for the key. More details in [the dedicated section in this README.md](./tools/localazy/README.md#key-naming-rules) More information can be found [in this README.md](./tools/localazy/README.md). Once a language is sufficiently translated, it will be added to the app. The core team will decide when a language is sufficiently translated. +### I want to fix a bug + +Please check if a corresponding issue exists, if not please create one. In both cases, let us know in the comment that you've started working on it. + +### I want to add 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 - Android, [iOS](https://github.com/element-hq/element-x-ios) and [Web/Desktop](https://github.com/element-hq/element-web). 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](https://github.com/element-hq/element-meta/issues) 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. + +## Developer onboarding + +For a detailed overview of the project, see [Developer Onboarding](./docs/_developer_onboarding.md). + +### Submitting the PRs + +Please have a look in the [dedicated documentation](./docs/pull_request.md) about pull request. + +### Android Studio settings + +Please set the "hard wrap" setting of Android Studio to 160 chars, this is the setting we use internally to format the source code (Menu `Settings/Editor/Code Style` then `Hard wrap at`). +Please ensure that you're using the project formatting rules (which are in the project at .idea/codeStyles/), and format the file before committing them. + +### Compilation + +This project should compile without any special action. Just clone it and open it with Android Studio, or compile from command line using `gradlew`. + +### Strings + +The strings of the project are managed externally using [https://localazy.com](https://localazy.com) and shared with Element X iOS. + ### Element X Android Gallery Once added to Localazy, translations can be checked screen per screen using our tool Element X Android Gallery, available at https://element-hq.github.io/element-x-android/. Localazy syncs occur every Monday and the screenshots on this page are generated every Tuesday, so you'll have to wait to see your change appearing on Element X Android Gallery. -## I want to add a new feature to Element X Android - -Thank you for contributing to the project! Please have a look in the [dedicated documentation](./docs/pull_request.md) about pull request. - -Also, please keep in mind that any feature added to Element X Android needs to be added to [the iOS client](https://github.com/element-hq/element-x-ios) too, unless it's related to an Android OS only behaviour. - -**IMPORTANT:** if you are adding new screens or modifying existing ones, this needs acceptance from the product and design teams before being merged. For this, it's better to start with a [feature request issue](https://github.com/element-hq/element-x-android/issues/new?template=enhancement.yml) describing the change you want to make and the motivation behind it instead of directly creating a pull request. This will allow the product and design teams to give feedback on the change before you start working on it, and avoid you doing work that might end up being rejected. - -## I want to submit a PR to fix an issue - -Please have a look in the [dedicated documentation](./docs/pull_request.md) about pull request. - -Please check if a corresponding issue exists. If yes, please let us know in a comment that you're working on it. -If an issue does not exist yet, it may be relevant to open a new issue and let us know that you're implementing it. - ### Kotlin This project is full Kotlin. Please do not write Java classes.