Skip to content

Latest commit

 

History

History
164 lines (129 loc) · 8.62 KB

CONTRIBUTING.md

File metadata and controls

164 lines (129 loc) · 8.62 KB
Raw

Contributing

Thanks for stopping by! This document should cover most topics surrounding contributing to bugsnag-cocoa.

Reporting issues

Are you having trouble getting started? Please contact us directly for assistance with integrating Bugsnag into your application. If you have spotted a problem with this module, feel free to open a new issue. Here are a few things to check before doing so:

  • Are you using the latest version of Bugsnag? If not, does updating to the latest version fix your issue?
  • Has somebody else already reported your issue? Feel free to add additional context to or check-in on an existing issue that matches your own.
  • Is your issue caused by this module? Only things related to the bugsnag-cocoa module should be reported here. For anything else, please contact us directly and we'd be happy to help you out.

Fixing issues

If you've identified a fix to a new or existing issue, we welcome contributions! Here are some helpful suggestions on contributing that help us merge your PR quickly and smoothly:

  • Fork the library on GitHub
  • Build and test your changes. We have automated tests for many scenarios but its also helpful to use npm pack to build the module locally and install it in a real app.
  • Commit and push until you are happy with your contribution
  • Make a pull request
  • Ensure the automated checks pass (and if it fails, please try to address the cause)

Adding features

Unfortunately we’re unable to accept PRs that add features or refactor the library at this time. However, we’re very eager and welcome to hearing feedback about the library so please contact us directly to discuss your idea, or open a feature request to help us improve the library.

Here’s a bit about our process designing and building the Bugsnag libraries:

  • We have an internal roadmap to plan out the features we build, and sometimes we will already be planning your suggested feature!
  • Our open source libraries span many languages and frameworks so we strive to ensure they are idiomatic on the given platform, but also consistent in terminology between platforms. That way the core concepts are familiar whether you adopt Bugsnag for one platform or many.
  • Finally, one of our goals is to ensure our libraries work reliably, even in crashy, multi-threaded environments. Oftentimes, this requires an intensive engineering design and code review process that adheres to our style and linting guidelines.

For an overview of source code organisation, see ORGANIZATION.md.

Testing

Run the unit tests for the Bugsnag library from Xcode or by running make test on the command-line. To specify a specific iOS SDK, run with the SDK name:

make SDK=iphonesimulator11.3 test

(The specified SDK must be installed in Xcode > Preferences > Components) Or test on macOS:

make PLATFORM=macOS test

Or to test on tvOS:

make PLATFORM=tvOS test

Run the integration tests - see TESTING.md.

Releasing

One time setup

  1. Install release tools using brew install cocoapods hub

  2. Sign in to CocoaPods trunk:

    pod trunk register notifiers@bugsnag.com 'Bugsnag Notifiers' --description='<your name>'

    (Remember to warn the platforms team to ignore the email)

  3. Click the link in the email that got sent to the platforms team

Pre-release steps

  • Check the master and next branches for what changes are intended to be released. If any changes on next should go out, check out that branch before the subsequent steps.

  • Add any missing entries to the CHANGELOG. Update the README if appropriate.

  • Create a pull request for a new version by running make VERSION=[number] prerelease. Pull request generation depends on hub (brew install hub)

  • Perform preflight checks:

    • Have the CHANGELOG and README been updated?
    • Are there pull requests for installation changes on the dashboard?
    • Are there pull requests for new features/behavior on the docs site?
    • Run pre-release checks - see instructions

  • Consider the following, additional checks based on changes in the release:

    • Has all new functionality been manually tested on a release build?

    • Do the installation instructions work when creating an example app from scratch? If using Cocoapods remember to point at the pre-release branch in the Podfile, e.g.

      pod 'Bugsnag', :git => 'https://github.com/bugsnag/bugsnag-cocoa', :branch => '<prerelease-branch-name>'

    • Does the Carthage installation instruction work?

    • If a response is not received from the server, is the report queued for later?

    • If no network connection is available, is the report queued for later?

    • On a throttled network, is the request timeout reasonable, and the main thread not blocked?

    • Are queued reports sent asynchronously?

    • On a throttled network, is the request timeout reasonable, and the main thread not blocked by any visible UI freeze? (Throttling can be achieved by setting both endpoints to "https://httpstat.us/200?sleep=5000")

    • Please ensure that release builds are run on a physical device with an ad-hoc archive. (For release builds, select Edit Scheme, change the Build Configuration to Release, and uncheck Debug Executable)

Release steps

  • Once the pull request is merged, publish the release by running make release
  • A GitHub release page will open. Fill in the release notes: vMaj.Min.Patch as a title and a summary of the changes from the CHANGELOG. Look to previous releases for style guidance; "This release fixes a number of issues..." etc.
  • Click "Publish Release".
  • Perform post-release checks:
    • Have all Docs and dashboard PRs been merged?
    • Do the installation instructions work using the released artefact?
    • Can a freshly created example app send an error report from a release build, using the released artefact?
    • Do the existing example apps send an error report using the released artefact?
  • Plan to make releases to downstream libraries once adoption of the main library has begun, if appropriate (generally for bug fixes). These include: