Copy over blog post

Experimental-package-releases-via-Stackage-Server.md

@@ -0,0 +1,89 @@
+This was originally [a blog post](https://www.fpcomplete.com/blog/2014/12/experimental-packages-stackage), and is now the official documentation on this feature.
+
+Right now, Hackage has no concept of a stable and an unstable release of a
+package. As a result, authors are hesitant to release code to Hackage unless
+it's already stable. But it's difficult to get people to test new versions of
+packages if it's difficult to install. Installing a single new package from
+Github may not be difficult, but sometimes you want people to test out a new
+set of versions for multiple packages, which can be tedious. This blog post
+will demonstrate how you can use Stackage Server to make that easy.
+
+While the primary purpose of [Stackage Server](http://www.stackage.org) is to host
+the official Stackage snapshots, it has been designed as completely generic server for hosting any set of
+packages desired, including custom packages not yet released to Hackage. All you need to do is:
+
+1. Create an account on Stackage Server (by [logging in with Google+ or Mozilla Persona](http://www.stackage.org/auth/login))
+2. Create a tarball in the correct format (described below)
+3. Upload it from [the snapshot upload page](http://www.stackage.org/upload)
+
+## Tarball format
+
+You can [download a sample bundle
+file](http://www.stackage.org/snapshot/2014-11-26-ghc78-exc/bundle) by clicking
+on the "Bundle" link at the top of [any snapshot
+page](http://www.stackage.org/snapshot/2014-11-26-ghc78-exc). It might be
+useful to open one up as you looking through the rest of this section.
+
+You can [view the tarball parsing
+code](https://github.com/fpco/stackage-server/blob/master/Handler/UploadStackage.hs#L141)
+in the Stackage Server codebase itself. The format is designed to be simple to
+replicate and extensible for future functionality. (In fact, the slug file
+feature I mention below was [only recently
+added](https://github.com/fpco/stackage-server/issues/37).)
+
+The tarball must be `tar`red in a format that [the tar
+package](http://www.stackage.org/package/tar) can read, and then gzipped. Each
+file in the tarball is treated indepedently. Directory structure inside the
+tarball is ignored. Using `tar cfz mybundle.tar.gz somedirectory` is usually
+sufficient to meet these criterion.
+
+Each file inside the tarball is treated separately. There are four kinds of
+files recognized:
+
+*   `desc` gives the human-readable title and description for the snapshot. Put the title on the first line, and the description on the following lines. (Note that, currently, we *only* display the title on the site, though we may add the description to the display in the future.)
+*   `slug` is a recommendation for the short name of the snapshot. For example, the [most recent GHC 7.8 snapshot](http://www.stackage.org/snapshot/2014-11-26-ghc78-exc) as I write this is `http://www.stackage.org/snapshot/2014-11-26-ghc78-exc`, which has a slug of `2014-11-26-ghc78-exc`. Slugs must be globally unique, so if someone else has already taken that slug, Stackage Server will append a randomized token to the end.
+
+*   `hackage` is a list of all the package/version combos to be included in this snapshot from Hackage. For example, you might have:
+
+    ```
+    foo-1.0.0
+    bar-1.0.1
+    ```
+
+    You're free to have multiple versions per package.
+
+*   Any file ending in `.tar.gz` will be treated as a *custom sdist tarball*, and will be made available for download from stackage.org. This is how you can provide custom versions of a package not released on Hackage. As an example of this, here's [a snapshot with two unreleased packages in it](http://www.stackage.org/snapshot/sample-stackage-bundle).
+
+## Custom snapshot
+
+Another use case is customizing an official Stackage snapshot. For example, you may be using a certain snapshot, but want to get a newer version of one of the packages from Hackage, or write a custom patch for one of the package versions and use that. If so, all you need to do is:
+
+1. Download the bundle file
+2. Tweak its contents
+3. Upload it
+4. Use the new URL
+
+## Replace or augment Hackage?
+
+The instructions for using a Stackage snapshot mention replacing the
+hackage.haskell.org remote-repo line in your cabal config file with the
+stackage.org URL. This makes sense if you're providing a snapshot that has all
+the packages from Hackage that you'll need. However, if you're testing out a
+few new packages, it's simpler to just provide those few extra packages, and
+add an *extra* remote-repo line to your config file instead of replacing the
+primary entry. Note that this trick can be used to augment a Stackage snapshot
+in addition to adding extra packages to Hackage.
+
+## Caveats
+
+You should keep two things in mind when using Stackage Server in this manner:
+
+* Snapshots you create live forever. In cases of extreme issues (like accidentally uploading copyrighted data) we will of course assist in removing the snapshot. But generally speaking, a snapshot is forever, just like uploading a package to Hackage makes it available forever.
+* All snapshots are [publicly listed](http://www.stackage.org/snapshots), so you don't want to put any sensitive information in there. Of course, the Stackage Server codebase is open source, so you're free to run your own, private instance if you'd like. Alternatively, FP Complete provides private Stackage Server instances as a service, feel free to [contact us for more information](https://www.fpcomplete.com/business/about/contact-us/).
+
+## Other uses
+
+Creating a generic tool like that has the advantage that it can be (ab)used to
+purposes other than the original intent of the author. In this case, I've
+described some intended alternate use cases for this functionality. If people
+come up with other unintended use cases, let me know!