Expand sourcemaps doc with release info

Author: dcramer

docs/sourcemaps.rst

@@ -3,69 +3,130 @@
 Source Maps
 ===========
 
-In various browsers Sentry supports deminifying JavaScript via source
-maps. A source map is a file generated by your minifier which compresses a
-mapping of the minified file to the original uncompressed version(s).
+In various browsers Sentry supports deminifying JavaScript via source maps. A source map is a file generated
+by your minifier which compresses a mapping of the minified file to the original uncompressed version(s).
 
-One important thing to note is that even though we support mapping files,
-a users browser may not actually be able to collect the required
-information for the server to generate a sourcemap.
+One important thing to note is that even though we support mapping files, a users browser may not actually be able
+to collect the required information for the server to generate a sourcemap.
 
-Sentry requires the following to be able to map tracebacks to their
-source:
+Sentry requires the following to be able to map tracebacks to their source:
 
-*   A source map header or footer
-*   A publicly accessible uncompressed version of the source
-*   A line of context that includes a line number, column number, and filename
+* A source map header or footer
+* A publicly accessible uncompressed version of the source
+* A line of context that includes a line number, column number, and filename
 
-The first two items are the responsibility of you, the end-user, and you
-can take care of publishing them as part of your build process. The latter
-however, with an individual line of context, is severely crippled in many
-browsers.
+The first two items are the responsibility of you, the end-user, and you can take care of publishing them as part
+of your build process. The latter however, with an individual line of context, is severely crippled in many browsers.
 
-One thing to note is that Sentry will attempt to process the source map
-before storing (or grouping) an event. This ensures that if we are able to
-deminify the source, we'll be able to more effectively group similar
-events over time.
+One thing to note is that Sentry will attempt to process the source map before storing (or grouping) an event. This ensures that if we are
+able to deminify the source, we'll be able to more effectively group similar events over time.</p>
 
 Browser Support
 ---------------
 
-In our experiences, the only browser that routinely delivers usable error
-reports is Google Chrome.
+In our experiences, the only browser that routinely delivers usable error reports is **Google Chrome**.
 
-For additional information, see this more up-to-date wiki page.
+For additional information, see this more up-to-date `wiki page <https://github.com/ryanseddon/source-map/wiki/Source-maps:-languages,-tools-and-other-inf>`_.
 
 Generating a Source Map
 -----------------------
 
-While there are several compression libraries which support source maps,
-as of writing our recommendation is to use UglifyJS.
+While there are several compression libraries which support source maps, as of writing our recommendation is to use
+`UglifyJS <https://github.com/mishoo/UglifyJS2>`_. That said, many tools such as `webpack <http://webpack.github.io/>`_ and `browserify <http://browserify.org/>`_.
 
-As an example, we can look at the Sentry source code to see how we
-generate internal source maps::
+As an example, we can look at how we used to do things with Sentry (pre-webpack):
 
-    node_modules/uglify-js/bin/uglifyjs {input}
-        --source-map-root={relroot}/
-        --source-map-url={name}.map.js
-        --source-map={relpath}/{name}.map.js -o {output}
+::
 
-We won't attempt to go into the complexities of source maps, so we
-recommend taking a stab at compiling them, and running them against a
-validator.
+    node_modules/uglify-js/bin/uglifyjs {input} \
+      --source-map-root={relroot}/ \
+      --source-map-url={name}.map.js \
+      --source-map={relpath}/{name}.map.js -o {output}
+
+We won't attempt to go into the complexities of source maps, so we recommend taking a stab at compiling them, and running them against a validator.
 
 Validating a Source Map
 -----------------------
 
-A third party tool is available to validate your source map:
-http://sourcemap-validator.herokuapp.com/
+We maintain an online validation tool that can be used to test your source (and sourcemaps) against: `sourcemaps.io <http://sourcemaps.io>`_.
+
+Uploading SourceMaps to Sentry
+------------------------------
+
+In many cases your application may sit behind firewalls or you simply can't expose source code to the public. Sentry provides an abstraction called
+**Releases** which you can attach source artifacts to.
+
+The release API is intended to allow you to store source files (and sourcemaps) within Sentry. This removes the requirement for them to be
+web-accessible, and also removes any inconsistency that could come from network flakiness (on either your end, or Sentry's end).
+
+* Start by creating a new API key under your organization's API Keys nav (on the home).
+
+* Ensure you you have ``project:write`` selected under scopes.
+
+* You'll use HTTP basic auth with the api key being your username, and an empty value for the password.
+
+Now you need to setup your build system to create a release, and attach the various source files. You will want to upload all dist
+files (i.e. the minified/shipped JS), the referenced sourcemaps, and the files that those sourcemaps point to.
+
+.. code-block:: bash
+
+    # Create a new release
+    $ curl https://app.getsentry.com/api/0/projects/:organization_slug/:project_slug/releases/ \
+      -u [api_key]: \
+      -X POST \
+      -d '{"version": "abcdef"}' \
+      -H 'Content-Type: application/json'
+
+    {
+      "dateCreated": "2015-03-06T04:51:32.723Z",
+      "version": "2da95dfb052f477380608d59d32b4ab9"
+    }
+
+.. code-block:: bash
+
+    # Upload a file for the given release
+    # Note: The filename should be the *full* url that this
+    # would be referenced as in production.
+    $ curl https://app.getsentry.com/api/0/projects/:organization_slug/:project_slug/releases/2da95dfb052f477380608d59d32b4ab9/files/ \
+      -u [api_key]: \
+      -X POST \
+      -F [email protected] \
+      -F name="http://example.com/readme.rst"
+
+    {
+      "dateCreated": "2015-03-06T04:53:00.308Z",
+      "headers": {
+        "Content-Type": "application/octet-stream"
+      },
+      "id": "1",
+      "name": "README.rst",
+      "sha1": "22591348ed129fe016c535654f6493737f0f9df6",
+      "size": 452
+    }
+
+.. code-block:: bash
+
+    # If you make a mistake, you can also simply clear out the release
+    $ curl https://app.getsentry.com/api/0/projects/:organization_slug/:project_slug/releases/2da95dfb052f477380608d59d32b4ab9/ \
+      -u [api_key]: \
+      -X DELETE
+
+Additionally, you'll need to configure [raven-js](https://github.com/getsentry/raven-js) to send the ``release``:
+
+.. code-block:: javascript
+
+    Raven.config({
+        release: '2da95dfb052f477380608d59d32b4ab9'
+    });
+
+Note: You dont *have* to upload the source files (ref'd by sourcemaps), but without them the grouping algorithm will not be as strong, and the UI will not show any contextual source.
+
+Additional information can be found in the `Releases API documentation <https://app.getsentry.com/docs/api/releases/>`_.
 
 .. sentry:edition:: hosted
 
-    Source Map Fetching
-    -------------------
+    Working Behind a Firewall
+    -------------------------
 
-    Source maps are dynamically fetched "in reverse".  If you are using
-    Sentry Cloud then you might want to restrict the access to those
-    sourcemaps by IP address.  For the IP ranges used by Sentry Cloud and
-    how to whitelist access please refer to :doc:`../../ip-ranges`.
+    While the recommended solution is to upload your source artifacts to Sentry, sometimes its nescessary to allow communication from Sentry's internal IPs. To
+    work around this you can whitelist our `:doc:`IP Ranges <../../ip-ranges>`.