Improve README.md and CONTRIBUTING.md (#548)

Author: stayallive

CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing to Sentry SDK for Laravel
+
+We welcome contributions to sentry-laravel 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.
+
+## How to report a problem
+
+Please search the [issue tracker](https://github.com/getsentry/sentry-laravel/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!
+
+If you feel that you can fix or implement it yourself, please read a few paragraphs below to learn how to submit your changes.
+
+## Submitting changes
+
+- Setup the development environment.
+- Clone sentry-laravel and prepare necessary changes.
+- Add tests for your changes to `tests/`.
+- Run tests and make sure all of them pass.
+- Submit a pull request, referencing any issues it addresses.
+
+We will review your pull request as soon as possible.
+Thank you for contributing!
+
+## Development environment
+
+### Clone the repo:
+
+```bash
+git clone [email protected]:getsentry/sentry-laravel.git
+```
+
+Make sure that you have PHP 7.2+ installed. Version 7.4 or higher is required to run style checkers. On macOS, we recommend using brew to install PHP. For Windows, we recommend an official PHP.net release.
+
+### Install the dependencies:
+
+Dependencies are managed through [Composer](https://getcomposer.org/):
+
+```bash
+composer install
+```
+
+### Running tests
+
+Tests can then be run via [PHPUnit](https://phpunit.de/):
+
+```bash
+composer test
+```
+
+## Releasing a new version
+
+(only relevant for Sentry employees)
+
+Prerequisites:
+
+- All the changes that should be release must be in `master` branch.
+- Every commit should follow the [Commit Message Format](https://develop.sentry.dev/commit-messages/#commit-message-format) convention.
+
+Manual Process:
+
+- Update CHANGELOG.md witht the version to be released. Example commit: https://github.com/getsentry/sentry-laravel/commit/a167e95c3c97cc5f9f315e96ef07a800aec3b440.
+- On GitHub in the `sentry-laravel` repository go to "Actions" select the "Release" workflow.
+- Click on "Run workflow" on the right side, 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. (See "Versioning Policy" below)
+- 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)
+
+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 immediatly 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 immediatly.
+
+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!
+
+There is a sequence diagram visualizing all this in the [README.md](https://github.com/getsentry/publish) of the `Publish` repository.
+
+### Versioning Policy
+
+This project follows [semver](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 (bugfixes and features). This project also follows that practice.
+
+- All undocumented APIs are considered internal. They are not part of this contract.
+
+- Certain features (e.g. integrations) may be explicitly called out as "experimental" or "unstable" in the documentation. They come with their own versioning policy described in the documentation.
+
+We recommend to pin your version requirements against `1.x.*` or `1.x.y`.
+Either one of the following is fine:
+
+```json
+"sentry/sentry": "^1.0",
+"sentry/sentry": "^1",
+```
+
+A major release `N` implies the previous release `N-1` will no longer receive updates. We generally do not backport bugfixes to older versions unless they are security relevant. However, feel free to ask for backports of specific commits on the bugtracker.
+
+## Commit message format guidelines
+
+See the documentation on commit messages here:
+
+https://develop.sentry.dev/commit-messages/#commit-message-format

README.md

@@ -4,51 +4,106 @@
     </a>
 </p>
 
-# Sentry for Laravel
+_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://secure.travis-ci.org/getsentry/sentry-laravel.png?branch=master)](http://travis-ci.org/getsentry/sentry-laravel)
-[![Total Downloads](https://img.shields.io/packagist/dt/sentry/sentry-laravel.svg?style=flat-square)](https://packagist.org/packages/sentry/sentry-laravel)
-[![Downloads per month](https://img.shields.io/packagist/dm/sentry/sentry-laravel.svg?style=flat-square)](https://packagist.org/packages/sentry/sentry-laravel)
-[![Latest stable version](https://img.shields.io/packagist/v/sentry/sentry-laravel.svg?style=flat-square)](https://packagist.org/packages/sentry/sentry-laravel)
-[![License](http://img.shields.io/packagist/l/sentry/sentry-laravel.svg?style=flat-square)](https://packagist.org/packages/sentry/sentry-laravel)
+# Official Sentry SDK for Laravel
 
-Laravel integration for [Sentry](https://sentry.io/).
+[![Build Status](https://img.shields.io/github/checks-status/getsentry/sentry-laravel/master)](https://github.com/getsentry/sentry-laravel/actions)
+[![Composer page link -- version](https://img.shields.io/packagist/v/getsentry/sentry-lararvel.svg)](https://packagist.org/packages/sentry/sentry-laravel)
+[![Discord](https://img.shields.io/discord/621778831602221064)](https://discord.gg/cWnMQeA)
 
-## Laravel Version Compatibility
+This is the official Laravel SDK for [Sentry](https://sentry.io/)
 
-- Laravel `<= 4.2.x` is supported until `0.8.x`
-- Laravel `<= 5.7.x` on PHP `<= 7.0` is supported until `0.11.x`
-- Laravel `>= 5.x.x` on PHP `>= 7.1` is supported in all versions
-- Laravel `>= 6.x.x` on PHP `>= 7.2` is supported starting from `1.2.0`
-- Laravel `>= 7.x.x` on PHP `>= 7.2` is supported starting from `1.7.0`
-- Laravel `>= 8.x.x` on PHP `>= 7.3` is supported starting from `1.9.0`
-- Laravel `>= 9.x.x` on PHP `>= 8.0` is supported starting from `2.11.0`
+---
+
+## Getting Started
 
-Please note that of version `>= 2.0.0` we require PHP Version `>= 7.2` because we are using our new [PHP SDK](https://github.com/getsentry/sentry-php) underneath. 
+The installation step below work on the latest versions of the Laravel framework (8.x and 9.x).
 
-## Installation
+For other Laravel or Lumen versions see:
 
 - [Laravel 8.x & 9.x](https://docs.sentry.io/platforms/php/guides/laravel/)
 - [Laravel 5.x, 6.x & 7.x](https://docs.sentry.io/platforms/php/guides/laravel/other-versions/laravel5-6-7/)
 - [Laravel 4.x](https://docs.sentry.io/platforms/php/guides/laravel/other-versions/laravel4/)
 - [Lumen](https://docs.sentry.io/platforms/php/guides/laravel/other-versions/lumen/)
 
-## Contributing
+### Install
 
-Dependencies are managed through [Composer](https://getcomposer.org/):
+Install the `sentry/sentry-laravel` package:
 
+```bash
+composer require sentry/sentry-laravel
 ```
-$ composer install
+
+Enable capturing unhandled exception to report to Sentry by making the following change to your `App/Exceptions/Handler.php`:
+
+```php {filename:App/Exceptions/Handler.php}
+public function register()
+{
+    $this->reportable(function (Throwable $e) {
+        if (app()->bound('sentry')) {
+            app('sentry')->captureException($e);
+        }
+    });
+}
 ```
 
-Tests can then be run via [PHPUnit](https://phpunit.de/):
+> Alternatively, you can configure Sentry in your [Laravel Log Channel](https://docs.sentry.io/platforms/php/guides/laravel/usage/#log-channels), allowing you to log `info` and `debug` as well.
+
+### Configure
 
+Configure the Sentry DSN with this command:
+
+```shell
+php artisan sentry:publish --dsn=___PUBLIC_DSN___
 ```
-$ vendor/bin/phpunit
+
+It creates the config file (`config/sentry.php`) and adds the `DSN` to your `.env` file.
+
+```shell {filename:.env}
+SENTRY_LARAVEL_DSN=___PUBLIC_DSN___
+```
+
+### Usage
+
+```php
+try {
+    $this->functionFailsForSure();
+} catch (\Throwable $exception) {
+    \Sentry\captureException($exception);
+}
 ```
 
-## Links
+- To learn more about how to use the SDK [refer to our docs](https://docs.sentry.io/platforms/php/guides/laravel/)
+
+## Laravel Version Compatibility
+
+- Laravel `<= 4.2.x` is supported until `0.8.x`
+- Laravel `<= 5.7.x` on PHP `<= 7.0` is supported until `0.11.x`
+- Laravel `>= 5.x.x` on PHP `>= 7.1` is supported in all versions
+- Laravel `>= 6.x.x` on PHP `>= 7.2` is supported starting from `1.2.0`
+- Laravel `>= 7.x.x` on PHP `>= 7.2` is supported starting from `1.7.0`
+- Laravel `>= 8.x.x` on PHP `>= 7.3` is supported starting from `1.9.0`
+- Laravel `>= 9.x.x` on PHP `>= 8.0` is supported starting from `2.11.0`
+
+Please note that of version `>= 2.0.0` we require PHP Version `>= 7.2` because we are using our new [PHP SDK](https://github.com/getsentry/sentry-php) underneath.
+
+## Contributing to the SDK
+
+Please refer to [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Getting help/support
+
+If you need help setting up or configuring the Laravel 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-sentry.io-green.svg)](https://docs.sentry.io/quickstart/)
+- [![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
 
-* [Documentation](https://docs.sentry.io/platforms/php/guides/laravel/)
-* [Bug Tracker](https://github.com/getsentry/sentry-laravel/issues)
-* [Code](https://github.com/getsentry/sentry-laravel)
+Licensed under the Apache 2.0 license, see [`LICENSE`](LICENSE)