review docs and prep rc0.4

Stephen Crosby
1 parent c0b84268
Showing 2 changed files with 109 additions and 223 deletions Show diff stats
CHANGELOG.md
README.md
-## 0.4.0 - Not released Yet
+## 0.4.0
 - #791 Fix double escaping of problem title in list view.(@felixbuenemann)
 - #790 Fix favicon location.(@felixbuenemann)
 - #716 Fix inline comments styles.(@oelmekki)
-- Update to rails 4.1.(@arthurnn)
+- #778 Update to rails 4.1.(@arthurnn)
 - #682 Namespace fingerprint classes better.(@csaunders)
 - Drop ruby support for versions 1.9.x, and 2.0.x.(@arthurnn)
-- #773 Only leave GitHub issue tracker on vanila errbit, as the others could be added just using the plugin.(@arthurnn)
+- #773 Only leave GitHub issue tracker on vanila errbit, as the others could be
+  added just using the plugin.(@arthurnn)
 - #768 Update to Mongoid 4.0 and rails to 4.0 (@arthurnn)
+- #820 Environment-only configuration
 ## 0.3.0
@@ -9,15 +9,11 @@
 [gemnasium-img-url]:https://gemnasium.com/errbit/errbit.png
 [gemnasium-url]:https://gemnasium.com/errbit/errbit
-
-
 ### The open source, self-hosted error catcher
-
 Errbit is a tool for collecting and managing errors from other applications.
-It is [Airbrake](http://airbrake.io) (formerly known as Hoptoad) API compliant,
-so if you are already using Airbrake, you can just point the `airbrake` gem to your Errbit server.
-
+It is [Airbrake](http://airbrake.io) API compliant, so if you are already using
+Airbrake, you can just point the `airbrake` gem to your Errbit server.
 <table>
   <tr>
@@ -52,10 +48,10 @@ so if you are already using Airbrake, you can just point the `airbrake` gem to y
   </tr>
 </table>
-
 Errbit may be a good fit for you if:
-* Your exceptions may contain sensitive data that you don't want sitting on someone else's server
+* Your exceptions may contain sensitive data that you don't want sitting on
+  someone else's server
 * Your application is behind a firewall
 * You'd like to brand your error catcher
 * You want to add customer features to your error catcher
@@ -64,26 +60,18 @@ Errbit may be a good fit for you if:
 If this doesn't sound like you, you should probably stick with a hosted service such as
 [Airbrake](http://airbrake.io).
-
 Mailing List
 ------------
-Join the Google Group at https://groups.google.com/group/errbit to receive updates and notifications.
-
-Demo
-----
-
-There is a demo available at [http://errbit-demo.herokuapp.com/](http://errbit-demo.herokuapp.com/)
-
-Email: demo@errbit-demo.herokuapp.com<br/>
-Password: password
+Join the Google Group at https://groups.google.com/group/errbit to receive
+updates and notifications.
 # Requirements
-The list of requirements to install Errbit are :
+The list of requirements to install Errbit are:
- * Ruby 2.1.0 or higher
- * MongoDB 2.2.0 or higher
+* Ruby 2.1.0 or higher
+* MongoDB 2.2.0 or higher
 Installation
 ------------
@@ -92,49 +80,11 @@ Installation
 Rails applications. If you're uncomfortable with any steps below then Errbit is not
 for you.
-**Set up your local box or server(Ubuntu):**
-
-  * Install MongoDB. Follow the directions [here](http://www.mongodb.org/display/DOCS/Ubuntu+and+Debian+packages), then:
-
-```bash
-apt-get update
-apt-get install mongodb-10gen
-```
-
-  * Install libxml, libzip, libssl and libcurl
-
-```bash
-apt-get install libxml2 libxml2-dev libxslt-dev libcurl4-openssl-dev libzip-dev libssl-dev
-```
-
-  * Install Bundler
-
-```bash
-gem install bundler
-```
-
-**Running Locally:**
-
-  * Install dependencies
-
-```bash
-bundle install
-```
-
-  * Install MongoDB. Follow the directions [here](http://www.mongodb.org/display/DOCS/Ubuntu+and+Debian+packages), then:
-
-  * Bootstrap Errbit. This will seed the database.  Make sure you copy the
-    username and password down someplace safe.
-
-```bash
-rake errbit:bootstrap
-```
-
-  * Start Server
-
-```bash
-rails s
-```
+* [Install MongoDB](https://www.mongodb.org/downloads)
+* git clone https://github.com/errbit/errbit.git
+* bundle install
+* bundle exec rake errbit:bootstrap
+* bundle exec rails server
 Configuration
 -------------
@@ -152,57 +102,63 @@ See [notes on deployment](docs/deployment.md)
 Authentication
 --------------
 ### Configuring GitHub authentication:
-* Set GITHUB_AUTHENTICATION to true
+* Set GITHUB_AUTHENTICATION=true
 * Register your instance of Errbit at https://github.com/settings/applications
-If you hosted Errbit at errbit.example.com, you would fill in:
+If you host Errbit at errbit.example.com, you would fill in:
-<table>
-  <tr><th>URL:</th><td><a href="http://errbit.example.com/">http://errbit.example.com/</a></td></tr>
-  <tr><th>Callback URL:</th><td><a href="http://errbit.example.com/users/auth/github">http://errbit.example.com/users/auth/github</a></td></tr>
-</table>
+<dl>
+<dt>URL
+<dd>http://errbit.example.com
+<dt>Callback URL
+<dd>http://errbit.example.com/users/auth/github
+</dl>
 * After you have registered your app, set GITHUB_CLIENT_ID and GITHUB_SECRET
   with your app's Client ID and Secret key.
 When you start your applicatoin, you should see the option to **Sign in with
-GitHub** on the Login page.
-
-You will also be able to link your GitHub profile to your user account on your
-**Edit profile** page.
-
-If you have signed in with GitHub, or linked your GitHub profile, and the App
-has a GitHub repo configured, then you will be able to create issues on GitHub.
-You will still be able to create an issue on the App's configured issue
-tracker.
-
-You can change the requested account permissions by setting
-`GITHUB_ACCESS_SCOPE` to:
-
-<table>
-  <tr><th>['repo'] </th><td>Allow creating issues for public and private repos.</td></tr>
-  <tr><th>['public_repo'] </th><td>Only allow creating issues for public repos.</td></tr>
-  <tr><th>[] </th><td>No permission to create issues on any repos.</td></tr>
-</table>
+GitHub** on the Login page. You will also be able to link your GitHub profile
+to your user account on your **Edit profile** page.
+
+If you have signed in with GitHub, or linked your GitHub profile, and you're
+working with an App that has a GitHub repo configured, then you will be able to
+create issues on GitHub. If you use another issue tracker, see [Issue
+Trackers](#issue-trackers).
+
+You can change the OAuth scope Errbit requests from GitHub by setting
+`GITHUB_ACCESS_SCOPE`. The default ['repo'] is very permissive, but there are a
+few others that could make sense for your needs:
+
+<dl>
+<dt>GITHUB_ACCESS_SCOPE="['repo']"</dt>
+<dd>Allow creating issues for public and private repos</dd>
+<dt>GITHUB_ACCESS_SCOPE="['public_repo']"</dt>
+<dd>Allow creating issues for public repos only</dd>
+<dt>GITHUB_ACCESS_SCOPE="[]"</dt>
+<dd>No permissions at all, but allows errbit login through github</dd>
+</dl>
 * GITHUB_ORG_ID is an optional environment variable you can set to your own
-  github organization id. If set, any user of the specified GitHub organization
-  can login.  If it is their first time, an account will automatically be
-  created for them.
+  github organization id. If set, only users of the specified GitHub
+  organization can log in to Errbit through GitHub. Errbit will provision
+  accounts for new users.
 ### Configuring LDAP authentication:
-  * Set `USER_HAS_USERNAME` to `true`
-  * Follow the instructions at https://github.com/cschiewek/devise_ldap_authenticatable
-    to set up the devise_ldap_authenticatable gem.
-  * Ensure to set ```config.ldap_create_user = true``` in ```config/initializers/devise.rb```, this enables creating the users from LDAP, otherwhise login will not work.
-  * Create a new initializer (e.g. ```config/initializers/devise_ldap.rb```) and add the following code to enable ldap authentication in the User-model:
+* Set USER_HAS_USERNAME=true
+* Follow the instructions at
+  https://github.com/cschiewek/devise_ldap_authenticatable to set up the
+  devise_ldap_authenticatable gem.
+* Set ```config.ldap_create_user = true``` in ```config/initializers/devise.rb```, this enables creating the users from LDAP, otherwhise login will not work.
+* Create a new initializer (e.g. ```config/initializers/devise_ldap.rb```) and add the following code to enable ldap authentication in the User-model:
+
 ```ruby
 Errbit::Config.devise_modules << :ldap_authenticatable
 ```
-  * If you are authenticating by `username`, you will need to set the user's email manually
-  before authentication. You must add the following lines to `app/models/user.rb`:
+* If you are authenticating by `username`, you will need to set the user's email manually
+before authentication. You must add the following lines to `app/models/user.rb`:
 ```ruby
   def ldap_before_save
@@ -215,8 +171,8 @@ Errbit::Config.devise_modules &lt;&lt; :ldap_authenticatable
   end
 ```
-  * Now login with your user from LDAP, this will create a user in the database
-  * Open a rails console and set the admin flag for your user:
+* Now login with your user from LDAP, this will create a user in the database
+* Open a rails console and set the admin flag for your user:
 ```ruby
 user = User.first
@@ -237,114 +193,55 @@ rake assets:precompile
 This will ensure that your application stays up to date with any schema changes.
+### Upgrading errbit from version 0.3 to 0.4
-### Upgrading errbit from version 0.2 to 0.3
-
-The MongoDB connection file `config/mongoid.yml` has changed between version 0.2 and
-0.3. We have provided a new example configuration file to use at `config/mongoid.example.yml`.
-
-This change is not needed if you use ENV variables to
-define access to your MongoDB database.
-
-
-## User information in error reports
-
-Errbit can now display information about the user who experienced an error.
-This gives you the ability to ask the user for more information,
-and let them know when you've fixed the bug.
-
-If you are running a Rails application and would like to include information
-about the current user in your error reports, you can replace the `airbrake`
-gem in your Gemfile with `airbrake_user_attributes`.
-This gem is a wrapper around the `airbrake` gem and will automatically
-inject information about the user into any error reports,
-so long as your controllers respond to a `#current_user` method.
-The user's attributes are filtered to remove authentication fields.
-
-If user information is received with an error report,
-it will be displayed under the *User Details* tab:
-
-
-![User details tab](http://errbit.github.com/errbit/images/error_user_information.png)
-
-(This tab will be hidden if no user information is available.)
+* All configuration is now done through the environment. See
+  [configuration](docs/configuration.md)
+* Ruby 1.9 and 2.0 are no longer offically supported. Please upgrade to Ruby
+  2.1+
+* Errbit now maintains an issue tracker only for github. If you're using
+  another issue tracker integration, you may need to maintain it yourself. See
+  (issue trackers)[#issue-trackers]
 Javascript error notifications
 --------------------------------------
-You can log javascript errors that occur in your application by including
+You can log javascript errors that occur in your application by including the
 [airbrake-js](https://github.com/airbrake/airbrake-js) javascript library.
-First you need to add airbrake-shim.js to your site and set some basic configuration
-options:
-
-```
-<script src="airbrake-shim.js" data-airbrake-project-id="ERRBIT API KEY" data-airbrake-project-key="ERRBIT API KEY" data-airbrake-environment-name="production" data-airbrake-host="http://errbit.yourdomain.com"></script>
-```
-
-Or you can just add shim file and set these options using:
+Install airbrake-js according to the docs at
+[airbrake-js](https://github.com/airbrake/airbrake-js) and set your project and
+host as early as possible:
-```
+```javascript
 Airbrake.setProject("ERRBIT API KEY", "ERRBIT API KEY");
 Airbrake.setHost("http://errbit.yourdomain.com");
 ```
-And that's it.
-
-Testing API V3 using ruby airbrake client
------------------------------------------
-
-If you want you test standard airbrake ruby gem with API V3. To do that you
-need to change your airbrake initializer file to something like this:
-
-```
-Airbrake.configure do |config|
-  config.api_key = ENV['airbrake_api_key']
-  config.host    = ENV['airbrake_host']
-  config.port    = ENV['airbrake_port'].to_i
-  config.secure  = ENV['airbrake_secure'] == 'true'
-  config.project_id = ENV['airbrake_api_key']
-end
-
-class Airbrake::Sender
-  def json_api_enabled?
-    true
-  end
-end
-```
-
-It is important to set project_id option to the same value as api_key, because
-project_id is required for building url to api endpoint. And airbrake has a bug
-that removes api_key from endpoint url. The only way to get this value is by passing
-it as project_id. This little monkey-patch is required because airbrake gem only
-uses v3 api when host is set to collect.airbrake.io.
-
-V3 request don't have framework option so you won't see this value in your error
-notices in errbit. Besides that everything looks the same. It was tested using
-rake airbrake:test for both v2 and v3.
-
 Using custom fingerprinting methods
 -----------------------------------
-Errbit allows you to use your own Fingerprinting Strategy.
-If you are upgrading from a very old version of errbit, you can use the `Fingerprint::MD5` for compatibility. The fingerprint strategy can be changed by adding an initializer to errbit:
+Errbit collates errors into groups using a fingerprinting strategy. If you find
+your errors are not getting grouped the way you would expect, you may need to
+implement your own strategy. A fingerprinting strategy is just a class that
+implements a ::generate class method. See the classes in
+`app/models/fingerprint/` if you need some inspiration. You can install it with
+an initializer like:
 ```ruby
-# config/fingerprint.rb
-ErrorReport.fingerprint_strategy = Fingerprint::MD5
+# config/initializers/fingerprint.rb
+ErrorReport.fingerprint_strategy = MyStrategy
 ```
-The easiest way to add custom fingerprint methods is to simply subclass `Fingerprint`
-
 Plugins and Integrations
 ------------------------
-You can extend Errbit by adding Ruby gems and plugins which are generally also
-gems. It's nice to keep track of which gems are core Errbit dependencies and
-which gems are your own dependencies. If you want to add gems to your own
-Errbit, place them in a new file called `UserGemfile`. If you want to use a
-file with a different name, you can pass the name of that file in an
-environment variable named `USER_GEMFILE`. For example, if you wanted to use
-errbit_jira_plugin, you could:
+You can extend Errbit by adding Ruby gems and plugins which are typically gems.
+It's nice to keep track of which gems are core Errbit dependencies and which
+gems are your own dependencies. If you want to add gems to your own Errbit,
+place them in a new file called `UserGemfile` and Errbit will treat that file
+as an additional Gemfile. If you want to use a file with a different name, you
+can pass the name of that file in an environment variable named `USER_GEMFILE`.
+If you want to use errbit_jira_plugin, just add it to UserGemfile:
 ```bash
 echo "gem 'errbit_jira_plugin'" > UserGemfile
@@ -361,38 +258,29 @@ supported issue tracker plugin is
 If you want to implement your own issue tracker plugin, read the README.md file
 at [errbit_plugin](https://github.com/errbit/errbit_plugin).
-Notification Service
---------------------
-**Flowdock Notification**
-
-Allow notification to [Flowdock](https://www.flowdock.com/). See
-[complete documentation](docs/notifications/flowdock/index.md)
-
-
 What if Errbit has an error?
 ----------------------------
-Errbit will log it's own errors to an internal app named **Self.Errbit**.
-The **Self.Errbit** app will be automatically created whenever the first error happens.
+Errbit will log it's own errors to an internal app named **Self.Errbit**.  The
+**Self.Errbit** app is automatically created when the first error happens.
-If your Errbit instance has logged an error, we would appreciate a bug report on GitHub Issues.
-You can post this manually at [https://github.com/errbit/errbit/issues](https://github.com/errbit/errbit/issues),
+If your Errbit instance has logged an error, we would appreciate a bug report
+on GitHub Issues. You can post this manually at
+[https://github.com/errbit/errbit/issues](https://github.com/errbit/errbit/issues),
 or you can set up the GitHub Issues tracker for your **Self.Errbit** app:
-  * Go to the **Self.Errbit** app's edit page. If that app does not exist yet, go to the apps page and click **Add a new App** to create it. (You can also create it by running `rake airbrake:test`.)
-
+  * Go to the **Self.Errbit** app's edit page. If that app does not exist yet,
+    go to the apps page and click **Add a new App** to create it. (You can also
+    create it by running `rake airbrake:test`.)
   * In the **Issue Tracker** section, click **GitHub Issues**.
-
   * Fill in the **Account/Repository** field with **errbit/errbit**.
-
   * Fill in the **Username** field with your github username.
-
-  * If you are logged in on [GitHub](https://github.com), you can find your **API Token** on this page: [https://github.com/account/admin](https://github.com/account/admin).
-
+  * If you are logged in on [GitHub](https://github.com), you can find your
+    **API Token** on this page:
+    [https://github.com/account/admin](https://github.com/account/admin).
   * Save the settings by clicking **Update App** (or **Add App**)
-
-  * You can now easily post bug reports to GitHub Issues by clicking the **Create Issue** button on a **Self.Errbit** error.
-
+  * You can now easily post bug reports to GitHub Issues by clicking the
+    **Create Issue** button on a **Self.Errbit** error.
 Use Errbit with applications written in other languages
 -------------------------------------------------------
@@ -415,17 +303,14 @@ Solutions known to work are listed below:
   </tr>
 </table>
-TODO
-----
-
-* Add ability for watchers to be configured for types of notifications they should receive
-
-
 People using Errbit
 -------------------
-See our wiki page for a [list of people and companies around the world who use Errbit](https://github.com/errbit/errbit/wiki/People-using-Errbit).
-Feel free to [edit this page](https://github.com/errbit/errbit/wiki/People-using-Errbit/_edit), and add your name and country to the list if you are using Errbit.
+See our wiki page for a [list of people and companies around the world who use
+Errbit](https://github.com/errbit/errbit/wiki/People-using-Errbit). You may
+[edit this
+page](https://github.com/errbit/errbit/wiki/People-using-Errbit/_edit), and add
+your name and country to the list if you are using Errbit.
 Special Thanks
@@ -440,8 +325,7 @@ Special Thanks
 * [Relevance](http://thinkrelevance.com) - For giving me Open-source Fridays to work on Errbit and all my awesome co-workers for giving feedback and inspiration.
 * [Thoughtbot](http://thoughtbot.com) - For being great open-source advocates and setting the bar with [Airbrake](http://airbrake.io).
-See the [contributors graph](https://github.com/errbit/errbit/graphs/contributors) for further details.
-
+See the [contributors graph](https://github.com/errbit/errbit/graphs/contributors) for more details.
 Contributing to Errbit
 ------------
@@ -456,4 +340,4 @@ Check the .travis.yml file to see how tests are run
 Copyright
 ---------
-Copyright (c) 2010-2014 Errbit Team. See LICENSE for details.
+Copyright (c) 2010-2015 Errbit Team