Skip to content

Latest commit

 

History

History
131 lines (82 loc) · 8.18 KB

CONTRIBUTING.md

File metadata and controls

131 lines (82 loc) · 8.18 KB
Raw


Contributing

We welcome suggested improvements and bug fixes for sentry-cocoa, in the form of pull requests. To get early feedback, we recommend opening up a draft PR. Please follow our official Commit Guidelines and also prefix the title of your PR according to the Commit Guidelines. The guide below will help you get started, but if you have further questions, please feel free to reach out on Discord.

PR reviews

For feedback in PRs, we use the LOGAF scale to specify how important a comment is:

  • l: low - nitpick. You may address this comment, but you don't have to.
  • m: medium - normal comment. Worth addressing and fixing.
  • h: high - Very important. We must not merge this PR without addressing this issue.

You only need one approval from a maintainer to be able to merge. For some PRs, asking specific or multiple people for review might be adequate.

Our different types of reviews:

  1. LGTM without any comments. You can merge immediately.
  2. LGTM with low and medium comments. The reviewer trusts you to resolve these comments yourself, and you don't need to wait for another approval.
  3. Only comments. You must address all the comments and need another review until you merge.
  4. Request changes. Only use if something critical is in the PR that absolutely must be addressed. We usually use h comments for that. When someone requests changes, the same person must approve the changes to allow merging. Use this sparingly.

Setting up an Environment

Run make init to get started. This will install pre-commit, bundler and Homebrew and their managed dependencies (see Gemfile and Brewfile).

Tests

The tests depend on our test server. To run the automated tests, you first need to have the server running locally with

make run-test-server

Test guidelines:

  • We write our tests in Swift. When touching a test file written in Objective-C consider converting it to Swift and then add your tests.
  • Make use of the fixture pattern for test setup code. For examples, checkout SentryClientTest or SentryHttpTransportTests.
  • Use TestData when possible to avoid setting up data classes with test values.
  • Name the variable of the class you are testing sut, which stands for system under test.
  • We prefer using Nimble over XCTest for test assertions. We can't use the latest Nimble version and are stuck with v10.0.0, cause it's the latest one that still supports Xcode 13.2.1, which we use in CI for running our tests. v11.0.0 already requires Swift 5.6 / Xcode 13.3.
  • When calling SentrySDK.start in a test, specify only the minimum integrations required to minimize side effects for tests and reduce flakiness.

Test can either be ran inside from Xcode or via

make test

Flaky tests

If you see a test being flaky, you should ideally fix it immediately. If that's not feasible, you can disable the test in the test scheme by unchecking it in the Test action:

Disabling test cases via the Xcode scheme

or by right-clicking it in the Tests Navigator (⌘6):

Disabling test cases via the Xcode Tests navigator

Then create a GH issue with the flaky test issue template.

Disabling the test in the scheme has the advantage that the test report will state "X tests passed, Y tests failed, Z tests skipped", as well as maintaining a centralized list of skipped tests (look in Sentry.xcscheme) and they will be grayed out when viewing in the Xcode Tests Navigator (⌘6):

How Xcode displays skipped tests in the Tests Navigator

Code Formatting

Please follow the convention of removing the copyright code comments at the top of files. We only keep them inside SentryCrash, as the code is based on KSCrash.

All Objective-C, C and C++ needs to be formatted with Clang Format. The configuration can be found in .clang-format. Simply run the make task, which runs automatically with git pre commit, before submitting your changes for review:

make format

GH actions suddenly formats code differently

It can be that it uses a different clang-format version, than you local computer. Please run brew install clang-format, and ensure that your version (run clang-format --version) matches the one from GH actions.

More information: We always use the latest version of clang-format in homebrew in our GH actions for formatting the code. As we use homebrew for setting up the development environment, homebrew only contains formulas for clang-format 8, 11, or the latest, and we want to use the latest clang-format version; we accept that we don't pin clang-format to a specific version. Using the GH action images clang-format version doesn't work, as it can be different than the one from homebrew. This means if homebrew updates the formula for the default clang-format version so does our GH actions job. If the GH actions job suddenly starts to format code differently than your local make format, please compare your clang-format version with the GH actions jobs version.

Linting

We use Swiftlint and Clang-Format. For SwiftLint, we keep a multiple config files for the tests and samples, cause some rules don't make sense for testing and sample code. To run all the linters locally execute:

make lint

Environment

Please use Sentry.xcworkspace as the entry point when opening the project in Xcode. It also contains all samples for different environments.

Public Headers

To make a header public follow these steps:

Configuring certificates and provisioning profiles locally

You can run samples in a real device without changing certificates and provisioning profiles if you are a Sentry employee with access to Sentry profiles repository and 1Password account.

  • Configure your environment to use SSH to access GitHub. Follow this instructions.
  • You will need Cocoa codesigning match encryption password from your Sentry 1Password account.
  • run fastlane match_local

This will setup certificates and provisioning profiles into your machine, but in order to be able to run a sample in a real device you need to register that device with Sentry AppConnect account, add the device to the provisioning profile you want to use, download the profile again and open it with Xcode.

Final Notes

When contributing to the codebase, please make note of the following:

  • Non-trivial PRs will not be accepted without tests (see above).
  • Please do not bump version numbers yourself.