Markdownify and extend README
authorHerbert Valerio Riedel <hvr@gnu.org>
Mon, 27 Apr 2015 06:29:51 +0000 (08:29 +0200)
committerHerbert Valerio Riedel <hvr@gnu.org>
Mon, 27 Apr 2015 06:30:39 +0000 (08:30 +0200)
README [deleted file]
README.md [new file with mode: 0644]
hoopl.cabal

diff --git a/README b/README
deleted file mode 100644 (file)
index 3de87b1..0000000
--- a/README
+++ /dev/null
@@ -1,28 +0,0 @@
-This repository contains things related to
-
-              Hoopl: A Higher-Order OPtimization Library
-
-** The closest thing we have to a SAMPLE CLIENT is in ./testing **
-
-Directory     Contents
-
-paper/        A paper about Hoopl
-prototypes/   A sampling of prototypes and early designs
-src/          The current official sources to the Cabal package
-testing/      Tests, including a sample client.  See ./testing/README.
-
-To build the library, change to the src directory and run
-
-  cabal configure --prefix=$HOME --user   # we have no idea what this means
-  cabal build
-  cabal install --enable-documentation
-
-You'll need a Haskell Platform, which should include appropriate
-versions of Cabal and GHC.
-
-To upload to Hackage,
-
-  cabal sdist
-  cabal upload dist/something.tar.gz
-
-Developers, please see HOWTO-BRANCHES
diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..d4b0129
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+The `hoopl` Package  [![Hackage](https://img.shields.io/hackage/v/hoopl.svg)](https://hackage.haskell.org/package/hoopl) [![Build Status](https://travis-ci.org/haskell/hoopl.svg)](https://travis-ci.org/haskell/hoopl)
+===================
+
+## Hoopl: A Higher-Order OPtimization Library
+
+API documentation can be found on [Hackage](https://hackage.haskell.org/package/directory).
+
+| Directory      | Contents
+| -------------- | ---------
+| `paper/`       | A paper about Hoopl
+| `prototypes/`  | A sampling of prototypes and early designs
+| `src/`         | The current official sources to the Cabal package
+| `testing/`     | Tests, including a sample client.  See [`testing/README`](testing/README)
+
+### Development Notes
+
+To build the library, change to the src directory and run
+
+    cabal configure --prefix=$HOME --user   # we have no idea what this means
+    cabal build
+    cabal install --enable-documentation
+
+You'll need a Haskell Platform, which should include appropriate
+versions of Cabal and GHC.
+
+### Checklist for Making Releases
+
+1. Make sure `hoopl` passes Travis for all GHC versions in the build-matrix
+2. Update Changelog (& `git commit`)
+3. Generate source tarball via `cabal sdist` and upload a candidate to Hackage (see note below), and inspect the result. 
+4. If everything checks out, make an annotated and GPG-signed Git release tag: `git tag -a -s v${VER} -m "hoopl ${VER}"`
+5. Publish (there's a button for that on Hackage) the package candidate
+6. Work on next release
+
+Note: To upload to Hackage,
+
+    cabal sdist
+    cabal upload dist/hoopl-*.tar.gz
+
+However, it's recommended use the Hackage feature for
+[uploading a candidate](http://hackage.haskell.org/packages/candidates/upload).
index 0fee9e2..9c88ae9 100644 (file)
@@ -18,7 +18,7 @@ Cabal-Version:       >=1.10
 Synopsis:            A library to support dataflow analysis and optimization
 Category:            Compilers/Interpreters
 Tested-With:         GHC>=7.0.1
-Extra-Source-Files:  README, hoopl.pdf, changelog.md
+Extra-Source-Files:  README.md, hoopl.pdf, changelog.md
 
 Source-repository head
   Type:       git