Bring README and CONTRIBUTING in line with SDKs (#620)

Closes #498.

Author: whatyouhide

CONTRIBUTING.md

@@ -1,51 +1,108 @@
-## Contributing
+# Contributing to the Sentry SDK for Elixir
 
-Contributions to Sentry Elixir are encouraged and welcome from everyone.
+We welcome contributions to `sentry-elixir` by the community. See the [Contributing to Docs](https://docs.sentry.io/contributing/) page if you want to fix or update the documentation on the website.
 
-Before submitting code, please run the test suite, format code according to Elixir's
-code formatter and [Credo](https://github.com/rrrene/credo). This can be done with
-`mix test`, `mix format` and `mix credo`.
+## How to Report a Problem
 
-The build server will also run [dialyzer](http://erlang.org/doc/man/dialyzer.html)
-using [dialyxir](https://github.com/jeremyjh/dialyxir) to check the typespecs, but this can be onerous
-to install and run. It is okay to submit changes without running it, but can
-be run with `mix dialyzer` if you would like to run them yourself.
+Please search the [issue tracker][issues] before creating a new issue (a problem or an improvement request). Please also ask in our [Sentry Community on Discord](https://discord.com/invite/Ww9hbqr) before submitting a new issue. There is a ton of great people in our Discord community ready to help you!
 
-Once all checks are passing, you are ready to [open a pull request](https://help.github.com/articles/using-pull-requests/).
+If you feel that you can fix or implement it yourself, please read a few paragraphs below to learn how to submit your changes.
 
-### Reviewing changes
+## Submitting Changes
 
-Once a pull request is sent, the changes will be reviewed.
+  * Set up the development environment.
+  * Clone `sentry-elixir` and prepare necessary changes.
+  * Add tests for your changes to `test/`.
+  * Run tests and make sure all of them pass.
+  * Submit a pull request, referencing any issues it addresses.
 
-If any changes are necessary, maintainers will leave comments requesting changes
-to the code. This does not guarantee a pull request will be accepted, as it will
-be reviewed following each change.
+We will review your pull request as soon as possible. Thank you for contributing!
 
-Once the code is approved, your changes will be merged!
+## Development Environment
 
-### Releasing a new version
+### Clone the Repo
 
-(only relevant for Sentry employees)
+```bash
+git clone [email protected]:getsentry/sentry-elixir.git
+```
+
+### Install Elixir and Fetch Dependencies
+
+Make sure that you have Elixir 1.15.x installed. Follow the official [Elixir installation guide](https://elixir-lang.org/install.html).
+
+Then, run this in your shell from the root of the cloned repository:
+
+```bash
+mix deps.get
+```
+
+You're ready to make changes.
+
+## Running Tests
+
+Before submitting code, please run the test suite and format code according to Elixir's code formatter. This can be done with:
+
+```bash
+mix test
+mix format
+```
+
+CI will also run [dialyzer](http://erlang.org/doc/man/dialyzer.html) using the [Dialyxir library](https://github.com/jeremyjh/dialyxir) to check the typespecs, but this can be onerous to install and run. It is okay to submit changes without running it. If you want to run it locally, run:
+
+```bash
+mix dialyzer
+```
+
+Once all checks are passing locally, you are ready to [open a pull request](https://help.github.com/articles/using-pull-requests/).
+
+That's it. You should be ready to make changes, run tests, and make commits! If you experience any problems, please don't hesitate to ping us in our [Discord Community](https://discord.com/invite/Ww9hbqr).
+
+## Releasing a New Version
+
+*(Only relevant for Sentry employees)*.
 
 Prerequisites:
 
-- All changes that should be released must be in the `master` branch.
+  * All changes that should be released must be in the `master` branch.
 
 Manual Process:
 
-- On GitHub in the `sentry-elixir` repository go to "Actions" select the "Release" workflow.
-- Click on "Run workflow" on the right side and make sure the `master` branch is selected.
-- Set "Version to release" input field. Here you decide if it is a major, minor or patch release.
-- Click "Run Workflow"
+  * [On GitHub][repo], go to "Actions" and select the "Release" workflow.
+  * Click on "Run workflow" on the right side and make sure the `master` branch is selected.
+  * Set "Version to release" input field. Here you decide if it is a major, minor or patch release.
+  * Click "Run Workflow".
 
-This will trigger [Craft](https://github.com/getsentry/craft) to prepare everything needed for a release. (For more information see [craft prepare](https://github.com/getsentry/craft#craft-prepare-preparing-a-new-release)) At the end of this process, a release issue is created in the [Publish](https://github.com/getsentry/publish) repository. (Example release issue: https://github.com/getsentry/publish/issues/815)
+This will trigger [Craft] to prepare everything needed for a release. (For more information see [craft prepare](https://github.com/getsentry/craft#craft-prepare-preparing-a-new-release)) At the end of this process, a release issue is created in the [`publish` repository][publish-repo]. (Example release issue: <https://github.com/getsentry/publish/issues/815>)
 
 Now one of the persons with release privileges (most probably your engineering manager) will review this Issue and then add the `accepted` label to the issue.
 
 There are always two persons involved in a release.
 
 If you are in a hurry and the release should be out immediately there is a Slack channel called `#proj-release-approval` where you can see your release issue and where you can ping people to please have a look immediately.
 
-When the release issue is labeled `accepted` [Craft](https://github.com/getsentry/craft) is triggered again to publish the release to all the right platforms. (See [craft publish](https://github.com/getsentry/craft#craft-publish-publishing-the-release) for more information). At the end of this process, the release issue on GitHub will be closed and the release is completed! Congratulations!
+When the release issue is labeled `accepted` [Craft] is triggered again to publish the release to all the right platforms. (See [craft publish](https://github.com/getsentry/craft#craft-publish-publishing-the-release) for more information). At the end of this process, the release issue on GitHub will be closed and the release is completed! Congratulations!
+
+There is a sequence diagram visualizing all this in the [README.md][publish-repo] of the `Publish` repository.
+
+### Versioning Policy
+
+This project follows the [SemVer specification](https://semver.org/), with three additions:
+
+  * SemVer says that major version `0` can include breaking changes at any time. Still, it is common practice to assume that only `0.x` releases (minor versions) can contain breaking changes while `0.x.y` releases (patch versions) are used for backwards-compatible changes (bug fixes and features). This project also follows that practice.
+
+  * All undocumented APIs are to be considered internal. They are not part of this contract.
+
+  * Certain features (such as integrations) may be explicitly called out as "experimental" or "unstable" in the documentation. They come with their own versioning policy described in the documentation.
+
+A major release `N` implies the previous release `N-1` will no longer receive updates. We generally do not backport bug fixes to older versions unless they are security relevant. However, feel free to ask for backports of specific commits on the issue tracker.
+
+## Commit Message Guidelines
+
+See the documentation on commit messages here:
+
+<https://develop.sentry.dev/commit-messages/#commit-message-format>
 
-There is a sequence diagram visualizing all this in the [README.md](https://github.com/getsentry/publish) of the `Publish` repository.
+[repo]: https://github.com/getsentry/sentry-elixir
+[issues]: https://github.com/getsentry/sentry-elixir/issues
+[Craft]: https://github.com/getsentry/craft
+[publish-repo]: https://github.com/getsentry/publish

README.md

@@ -1,14 +1,22 @@
-# Sentry
+<p align="center">
+  <a href="https://sentry.io/?utm_source=github&utm_medium=logo" target="_blank">
+    <img src="https://sentry-brand.storage.googleapis.com/sentry-wordmark-dark-280x84.png" alt="Sentry" width="280" height="84">
+  </a>
+</p>
+
+_Bad software is everywhere, and we're tired of it. Sentry is on a mission to help developers write better software faster, so we can get back to enjoying technology. If you want to join us [<kbd>**Check out our open positions**</kbd>](https://sentry.io/careers/)_
 
 ![Build Status](https://github.com/getsentry/sentry-elixir/actions/workflows/main.yml/badge.svg)
 [![Hex Package](https://img.shields.io/hexpm/v/sentry.svg)](https://hex.pm/packages/sentry)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-blue.svg)](https://hexdocs.pm/sentry)
 
-The official Sentry client for Elixir which provides a simple API to capture exceptions, automatically handle Plug exceptions, and provides a backend for the Elixir Logger.
+This is the official Sentry SDK for [Sentry].
+
+*💁: This README documents unreleased features (from the `master` branch). For documentation on the current release, see [the official documentation][docs].*
 
-💁: This README documents unreleased features (from the `master` branch). For documentation on the current release, see [the official documentation][docs].
+## Getting Started
 
-## Installation
+### Install
 
 To use Sentry in your project, add it as a dependency in your `mix.exs` file. Sentry does not install a JSON library nor HTTP client by itself. Sentry will default to trying to use [Jason] for JSON serialization and [Hackney] for HTTP requests, but can be configured to use other ones. To use the default ones, do:
 
@@ -17,18 +25,28 @@ defp deps do
   [
     # ...
 
-    {:sentry, "8.0.0"},
+    {:sentry, "~> 9.0"},
     {:jason, "~> 1.4"},
     {:hackney, "~> 1.19"}
   ]
 end
 ```
 
-## Usage
+### Configuration
 
-This is a short overview of how to use the library. For complete documentation, refer to [HexDocs][docs].
+Sentry has a range of configuration options, but most applications will have a configuration that looks like the following:
 
-### Capture Crashed Process Exceptions
+```elixir
+# config/config.exs
+config :sentry,
+  dsn: "https://[email protected]/1",
+  environment_name: Mix.env(),
+  included_environments: [:prod],
+  enable_source_code_context: true,
+  root_source_code_paths: [File.cwd!()]
+```
+
+### Usage
 
 This library comes with a [`:logger` handler][logger-handlers] to capture error messages coming from process crashes. To enable this, add the handler when your application starts:
 
@@ -42,8 +60,6 @@ This library comes with a [`:logger` handler][logger-handlers] to capture error
 
 The handler can also be configured to capture `Logger` metadata. See the documentation [here](https://hexdocs.pm/sentry/Sentry.LoggerBackend.html).
 
-### Capture Arbitrary Exceptions
-
 Sometimes you want to capture specific exceptions manually. To do so, use [`Sentry.capture_exception/2`](https://hexdocs.pm/sentry/Sentry.html#capture_exception/2).
 
 ```elixir
@@ -55,29 +71,37 @@ rescue
 end
 ```
 
-### Capture Non-Exception Events
-
 Sometimes you want to capture **messages** that are not exceptions. To do that, use [`Sentry.capture_message/2`](https://hexdocs.pm/sentry/Sentry.html#capture_exception/2):
 
 ```elixir
 Sentry.capture_message("custom_event_name", extra: %{extra: information})
 ```
 
-For optional settings check the [documentation][docs].
+To learn more about how to use this SDK, refer to [the documentation][docs].
 
-## Configuration
+## Integrations
 
-Sentry has a range of configuration options, but most applications will have a configuration that looks like the following:
+  * [Phoenix and Plug][setup-phoenix-and-plug]
 
-```elixir
-# config/config.exs
-config :sentry,
-  dsn: "https://[email protected]/1",
-  environment_name: Mix.env(),
-  included_environments: [:prod],
-  enable_source_code_context: true,
-  root_source_code_paths: [File.cwd!()]
-```
+## Contributing to the SDK
+
+Please refer to [`CONTRIBUTING.md``](CONTRIBUTING.md).
+
+## Getting Help/Support
+
+If you need help setting up or configuring the Python SDK (or anything else in the Sentry universe) please head over to the [Sentry Community on Discord](https://discord.com/invite/Ww9hbqr). There is a ton of great people in our Discord community ready to help you!
+
+## Resources
+
+  * [![Documentation](https://img.shields.io/badge/documentation-hexdocs.svg)][docs]
+  * [![Forum](https://img.shields.io/badge/forum-sentry-green.svg)](https://forum.sentry.io/c/sdks)
+  * [![Discord](https://img.shields.io/discord/621778831602221064)](https://discord.gg/Ww9hbqr)
+  * [![Stack Overflow](https://img.shields.io/badge/stack%20overflow-sentry-green.svg)](http://stackoverflow.com/questions/tagged/sentry)
+  * [![Twitter Follow](https://img.shields.io/twitter/follow/getsentry?label=getsentry&style=social)](https://twitter.com/intent/follow?screen_name=getsentry)
+
+## License
+
+Licensed under the MIT license, see [`LICENSE`](./LICENSE).
 
 ### Context and Breadcrumbs
 
@@ -192,11 +216,11 @@ end
 
 When testing, you will also want to set the `send_result` type to `:sync`, so the request is done synchronously.
 
-## License
 
-This project is Licensed under the [MIT License](https://github.com/getsentry/sentry-elixir/blob/master/LICENSE).
 
+[Sentry]: http://sentry.io/
 [Jason]: https://github.com/michalmuskala/jason
 [Hackney]: https://github.com/benoitc/hackney
 [docs]: https://hexdocs.pm/sentry/readme.html
 [logger-handlers]: https://www.erlang.org/doc/apps/kernel/logger_chapter#handlers
+[setup-phoenix-and-plug]: https://hexdocs.pm/sentry/setup-with-plug-and-phoenix.html