Files
simplex-chat/docs/CONTRIBUTING.md
T
Evgeny @ SimpleX Chat 2a0ebcf0cd ci, tests: run all tests in CI (#8238)
* bots, tests: run broadcast bot test in CI

* tests: test moderation that arrives before the message

* ci, tests: run all tests in CI

* tests: update re-enabled tests, restore query plans, PostgreSQL schema from CI

* tests: remove CI skip helpers no longer used

* tests: expect XFTP AUTH error of cancelled standalone file

* tests: update query plans from CI

* tests: update query plans from CI

* tests: expect group history and member contacts in async group test

* tests: accept subscription summary after first events on restart

* tests: make AUTH and client timeout direct tests deterministic

* tests: keep bob's badge clock before renewal until the move back

* tests: keep the quota of 2 messages only on the member's receive queue

* tests: keep query plans files with repeated entries of one query

* tests: update query plans from CI

* tests: stop the host before a member requests to join with a badge

* tests: remove repeated entries of one query from query plans files

* tests: accept the refusal of an unknown remote host after its session code

* ci: state when the query plans test fails

* tests: skip multicast discovery on macOS CI runners

* tests: accept a remote host started with one local address

* tests: restore the client timeout test except its zero timeout

* tests: fail when a remote host prints another line than its other addresses

* ci: name the tests that overwrite generated files

* tests: move the badge clock after the restoring device arms its wake

* tests: keep both members on the quota server in the member inactivity test

* tests: accept subscription summaries in any order in the async group test

* tests: update query plans from CI

* tests: quota of 2 only on bob's queues in member inactivity test

* tests: connect to a deleted link after its queue is deleted

* core: save relay connection before requesting relay link data

* core: share relay connection creation between join and retry

* tests: connect to a re-added relay when its connection is saved late

* tests: delay only the relay connection record, not the command

* tests: record API fixtures on SQLite only

* core: update query plans

* ci: run PostgreSQL tests with the steps of build-linux
2026-11-21 17:34:57 +00:00

156 lines
7.6 KiB
Markdown

---
title: Contributing guide
revision: 25.07.2025
---
| Updated 25.07.2025 | Languages: EN, [FR](/docs/lang/fr/CONTRIBUTING.md), [CZ](/docs/lang/cs/CONTRIBUTING.md), [PL](/docs/lang/pl/CONTRIBUTING.md) |
# Contributing guide
## Focus on user problems
We do not make code changes to improve code - any change must address a specific user problem or request.
## Discuss the plans as early as possible
Please discuss the problem you want to solve and your detailed implementation plan with the project team prior to contributing, to avoid wasted time and additional changes. Acceptance of your contribution depends on your willingness and ability to iterate the proposed contribution to achieve the required quality level, coding style, test coverage, and alignment with user requirements as they are understood by the project team.
## Follow project structure, coding style and approaches
./contributing/PROJECT.md has information about the structure of this `simplex-chat` repository.
./contributing/CODE.md has details about general requirements common for `simplexmq` and `simplex-chat` repositories.
./contributing/TESTS.md has the testing approaches of this repository: the tests required for a change, how they are written and run, and where CI runs them.
CLAUDE.md in the repository root imports these files, this guide and ../scripts/ci/README.md for Claude Code; apps/ios/CLAUDE.md and apps/multiplatform/CLAUDE.md import the README of each app.
## Compiling with SQLCipher encryption enabled
Add `cabal.project.local` to project root with the location of OpenSSL headers and libraries and flag setting encryption mode:
```
cp scripts/cabal.project.local.mac cabal.project.local
# or
# cp scripts/cabal.project.local.linux cabal.project.local
```
## OpenSSL on MacOS
MacOS comes with LibreSSL as default, OpenSSL must be installed to compile SimpleX from source.
OpenSSL can be installed with `brew install openssl@3.0`
You will have to add `/opt/homebrew/opt/openssl@3.0/bin` to your PATH in order to have things working properly
## Project branches
**In simplex-chat repo**
- `stable` - stable release of the apps, can be used for updates to the previous stable release (GHC 9.6.3).
- `master` - branch for beta version releases (compatible with both GHC 9.6.3 and 8.10.7). Nix builds Android armv7a core library with GHC 8.10.7 and all other core libraries with GHC 9.6.3.
**In simplexmq repo**
- `master` - compatible with both GHC 9.6.3 and 8.10.7.
## Development & release process
1. Make PRs to `master` branch _only_ for both simplex-chat and simplexmq repos.
2. To build core libraries for Android, iOS and Windows, push `master` branch to GitHub.
3. All libraries should be built from `master` branch.
4. To build Desktop and CLI apps, make tag in `master` branch, APK files should be attached to the release.
5. After the public release to App Store and Play Store, merge `master` to `stable`.
6. Independently, `master` branch of simplexmq repo should be merged to `stable` branch on stable releases.
## Branches and PRs
Use change scope (or comma separated scopes) as the first word in the PR names, followed by the colon. Commit name itself should be lowercase, in present tense.
The PR names in simplex-chat repo are used in release notes, they should describe the solved problem and not the change. Possible PR scopes:
- ios
- android
- desktop
- core
- docs
- website
- ci
We squash PRs, do not rewrite branch history after the review.
For some complex features we create feature branches that will be merged once ready - do not make commits directly to them, make PRs to feature branches.
## Pull requests and CI
1. Open a pull request to `master` as a draft. On a draft, CI runs the reduced build: one Linux job that builds and tests the changed scopes, one Linux job that runs the core tests on PostgreSQL when core code changed, and one macOS job only when iOS code changed (CI guide: scripts/ci/README.md).
2. Select the core tests in a `ci-tests` block in the description, one hspec match pattern per line. `/` runs all tests; without a block, the reduced build runs no core tests.
3. Push further changes to the same branch; on a draft, each push runs the reduced build.
4. Mark the pull request ready for review once it is ready. CI then runs the full matrix on each push, and the code owners are requested for review.
5. Mark it as a draft again when more work is needed. After the approval, the pull request is merged by squash once CI passes.
6. A change to a scope without CI tests adds its build and tests to CI in the same pull request.
7. A change of the apps' code adds, in the same pull request, app tests of all its changes on the core's real responses: core tests record the responses and events in tests/fixtures/api, and the Kotlin and iOS tests run the app code on them, with any platform service the code calls mocked (CI guide: "App test fixtures").
8. Files that tests generate (schema dumps, query plans, API docs) are committed as CI generates them: when a test changes one, the step "Check generated files" fails, and the run's artifact `generated-files-<job>` holds the change as a patch.
## Differences between GHC 8.10.7 and GHC 9.6.3
1. The main difference is related to `DuplicateRecordFields` extension.
It is no longer possible in GHC 9.6.3 to specify type when using selectors, instead OverloadedRecordDot extension and syntax are used that need to be removed in GHC 8.10.7:
```haskell
{-# LANGUAGE DuplicateRecordFields #-}
-- use this in GHC 9.6.3 when needed
{-# LANGUAGE OverloadedRecordDot #-}
-- GHC 9.6.3 syntax
let x = record.field
-- GHC 8.10.7 syntax removed in GHC 9.6.3
let x = field (record :: Record)
```
It is still possible to specify type when using record update syntax, use this pragma to suppress compiler warning:
```haskell
-- use this in GHC 9.6.3 when needed
{-# OPTIONS_GHC -fno-warn-ambiguous-fields #-}
let r' = (record :: Record) {field = value}
```
2. Most monad functions now have to be imported from `Control.Monad`, and not from specific monad modules (e.g. `Control.Monad.Except`).
```haskell
-- use this in GHC 9.6.3 when needed
import Control.Monad
```
[This PR](https://github.com/simplex-chat/simplex-chat/pull/2975/files) has all the differences.
## Improving compatibility between versions for remote desktop connection
UI already can handle failed JSON conversions of chats and chat items, and it helps both debugging and downgrading.
While we can increase versions for remote connections to make different versions incompatible, it degrades remote connection UX, as in many cases users can't upgrade mobile or desktop apps at the same time because of different release cycles.
It is especially problematic for Android app users, as they can only downgrade via Export/Import - older version can't be installed on top of newer version.
PR #6105 improved it by:
- adding CInfoInvalidJSON constructor, so that chats that cannot be parsed will show as "invalid chat" via remote connection (as when UI has field not present in API),
- changing JSON parsing for CIContent, so that it falls back to CIInvalidJSON in platform-specific JSON parser.
To avoid "invalid" chats in the list we need to maintain forward compatibility on JSON encoding level of AChat type and subtypes:
- add new fields as optional to these types,
- add `omittedField` method to FromJSON instances of types of new fields to provide a default value, where appropriate,
- define primitive non-optional fields as newtype with `omittedField` in JSON instance.
To avoid fallback to invalid JSON in chat items we should do the same for ChatItem type and subtypes. It's especially important when adding fields to types used for all CIContent, as otherwise all items will be broken.