Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
125 lines (87 loc) · 5.23 KB

CONTRIBUTING.md

File metadata and controls

125 lines (87 loc) · 5.23 KB
Raw


General Guidance

You can contribute to this project in the following ways:

  • Try out the master branch and provide feedback
  • File a bug report or propose a feature
  • Open a PR for bug fixes or implement requested features
  • Give feedback to opened issues/pull requests
  • Contribute documentation in the sentry-doc repo

And if you have any questions, please feel free to reach out on Discord.

Develop This Project With Multi-root Workspaces

If you use editors that support VS Code-style multi-root workspaces, such as VS Code, Cursor...etc., opening the editor with sentry-ruby.code-workspace file will provide a better development experience.

Working in a devcontainer

If you use Dev Containers extension, you can open the project with the devcontainer by running Remote-Containers: Reopen in Container command.

The devcontainer is configured with .devcontainer/.env file, that you need to create:

cp .devcontainer/.env.example .devcontainer/.env

This file defines which specific image and Ruby version will be used to run the code. Edit it whenever you need to use a different image or Ruby version.

Contribute To Individual Gems

  • Install the dependencies of a specific gem by running bundle in it's subdirectory. I.e: 
    cd sentry-sidekiq
bundle install
  • Install any additional dependencies. sentry-sidekiq assumes you have redis running.
  • Use the ./bin/test helper to run tests.
    • In sentry-rails, you can use RAILS_VERSION=version to specify the Rails version to test against. Default is 8.0
    • In sentry-sidekiq, you can use SIDEKIQ_VERSION=version to specify what version of Sidekiq to install when you run bundle install. Default is 7.0
  • Use example apps under the example or examples folder to test the change. (Remember to change the DSN first)
  • To learn more about sentry-ruby's structure, you can read the Sentry SDK spec

Regenerating CI Lockfiles

CI installs against a committed, checksummed lockfile per test-matrix cell (<gem>/gemfiles/<cell>.gemfile.lock) to keep dependencies fully pinned against supply chain attacks. Each gem's test-matrix.json is the source of truth; bin/relock materializes the gemfiles and locks from it.

We use mise for managing the ruby versions, so first install that by following official instructions. The required Rubies are declared in .mise.ci.toml, so provision them once:

mise --env ci install            # installs every Ruby the matrix needs

Then regenerate locks:

bin/relock                                   # every cell
bin/relock --gem sentry-ruby                 # one gem
bin/relock --cell sentry-ruby/gemfiles/ruby-3.2_rack-3_redis-5.gemfile  # one cell

In CI, the Update lockfiles workflow runs relock on a weekly schedule and opens a PR with the refreshed pins.

Compiling old rubies

Old rubies are not available pre-compiled by mise so you might need some additional flags depending on your system:

On latest macos, Ruby 3.0 needs a patch to compile:

MISE_RUBY_APPLY_PATCHES="https://github.com/ruby/ruby/commit/1dfe75b0beb7171b8154ff0856d5149be0207724.patch" \
  mise install ruby@3.0

On new linuxes with a very new gcc, you might need:

CFLAGS="-std=gnu11" mise install ruby@2.7

Write Your Sentry Extension

Please read the extension guideline to learn more. Feel free to open an issue if you find anything missing.

Release SDK Gem

Before the Release

  1. Run the example app(s) of the gem and make sure all the events are reported successfully.
  2. Update the changelog's latest Unreleased title with the target version.

Minor-version releases

  • Make sure all the new features are documented properly in the changelog. This includes but not limited to:
    • Explanation of the feature.
    • Sample code for the feature.
    • Expected changes on the SDK's behavior and/or on the reported events.
    • Some related screenshots.
  • Prepare a PR in the sentry-doc repo to update relevant content depending on the changes in the new release.

Major-version releases

In addition to all the steps listed above, you also need to:

  • Write a migration guide to
    • Outline the major changes done in this release.
    • Explain why upgrading is beneficial.
    • List all the breaking changes and help users make related changes in their apps.
  • Update gem READMEs.
  • May need to check related wizard files in the sentry-doc repo.