update readme and release instructions

close #142

Author: duncdrum

README.md

@@ -1,49 +1,41 @@
-eXist-db Documentation
-======================
+# eXist-db Documentation
 [![Build Status](https://travis-ci.org/eXist-db/documentation.svg?branch=master)](https://travis-ci.org/eXist-db/documentation)
+[![docbook version](https://img.shields.io/badge/docbook-4.5-19a5a4.svg)](http://docbook.org/xml/4.5/)
+[![docbook version](https://img.shields.io/badge/eXist_db-3.5.0-blue.svg)](http://www.exist-db.org/exist/apps/homepage/index.html)
 
-This repository contains the official documentation for the eXist-db Native XML database and the application for browsing it.
+<img src="src/main/xar-resources/icon.png" align="left" width="15%"/>
 
-## Resources
+This repository contains the official documentation for the [eXist-db native XML database](http://www.exist-db.org) and the application for browsing it. You can browse the latest release of the documentation on [eXist-db homepage](http://exist-db.org/exist/apps/doc/). User reporting errors should check the [contributions](#contributions) section below. Core-contributors preparing a release should consult the [release procedure](RELEASE.md)
 
-- Browse the latest release of the documentation at http://exist-db.org/exist/apps/doc/. 
-- The documentation app is included by default in the eXist-db installer. Just go to your eXist server's Dashboard and select Documentation.
-- Update to the latest release via the eXist-db package manager or via the eXist-db.org public app repository at <http://exist-db.org/exist/apps/public-repo/>.
 
-## Building from source
-
-1. Dependencies: Maven 3.x
-
-2. Clone the repository to your system:
-
-```bash
-$ git clone https://github.com/exist-db/documentation.git exist-documentation
-```
-
-3. Build the documentation application:
-```bash
-$ cd exist-documentation
-$ mvn clean package
-```
-
-4. An EXPath Application Package (.xar file) is deposited in the `target` directory
+## Dependencies
+-   [Maven](https://maven.apache.org): 3.x
+-   [eXist-db](http://exist-db.org): 3.5.0
 
-5. Install this file via the Dashboard > Package Manager.
+## Installation
+-   The default eXist-db installer includes the documentation app. Just go to your eXist server's Dashboard and select Documentation.
+-   If you need to install an older version, you can download EXPath Application Packages (`.xar` files) of previous [releases](https://github.com/eXist-db/documentation/releases) from GitHub.
+-   Update to the latest release via the eXist-db package manager or via the eXist-db.org public app repository at [http://exist-db.org/exist/apps/public-repo/](http://exist-db.org/exist/apps/public-repo/).
 
-Find an area of the documentation that needs to be improved? Please raise an issue and submit a pull request!
+## Contributions
+Found an area of the documentation that needs to be improved? Please raise an [issue](https://github.com/eXist-db/documentation/issues) or better yet submit a [pull request](https://github.com/eXist-db/documentation/pulls)!
 
+Our test-suite performs a validation check on all articles when you open a pull request. You can speed up the review process by running `mvn validate` locally before submitting a pull request.
 
-## Building a Release from source
-
-1. Follow the instructions from [Building from source](#building-from-source)
-
-2. Create a Release:
-
-```bash
-$ mvn release:prepare
-$ mvn release:perform
-```
-
-3. An EXPath Application Package (.xar file) is deposited in the `target` directory
-
-4. If you are a core contributor, you should then commit and push.
+## Building from source
+1.  Clone the repository to your system:
+    ```bash
+    $ git clone https://github.com/exist-db/documentation.git exist-documentation
+    ```
+
+2.  Build the documentation application:
+    ```bash
+    $ cd exist-documentation
+    $ mvn clean package
+    ```
+    The compiled `.xar` file is located in the `/target` directory
+
+3.  Install this file via the Dashboard > Package Manager.
+
+## License
+LGPLv2.1 [eXist-db.org](http://exist-db.org/exist/apps/homepage/index.html)

RELEASE.md

@@ -0,0 +1,54 @@
+# Release Procedure
+Core-contributors should follow these steps when publishing a new release of the documentation app.  
+
+## Local Environment Checks
+-   maven requires a valid gpg key associated with your GitHub account to publish a new release, to check your available keys:
+```bash
+gpg --list-keys
+```
+-   You can perform a dry-run of the release procedure by executing
+```bash
+$ mvn -DdryRun=true release:prepare
+```
+-   Dry-runs still create files that will interfere with regular releases. You should therefore clean up afterwards by running:
+```bash
+$ mvn release:rollback
+```
+
+
+## Preparing the Release Commit
+1.  Merge outstanding and reviewed PRs.
+
+2.  Set the `exist.version` in  `pom.xml` to prevent users of older exist releases, from installing the wrong documentation locally. Since the canonical version needs to run on exist-db.org please make sure that the main server can actually run the latest documentation, and raise an issue if necessary.
+
+3.  To generate the release notes run:
+```bash
+$ mvn changes:github-report
+```
+
+this will generate a `github-report.html` in `target/site` you can copy the list of changes into `xar-assembly.xml` describing which articles changed and how.
+
+## Building the Release
+4.  Follow the instructions from [Building from source](README.md#building-from-source)
+
+5.  To create a release run:
+```bash
+$ mvn release:prepare
+$ mvn release:perform
+```
+
+When prompted to pick a version number for the release, remember to mirror the [major version](https://github.com/eXist-db/exist/blob/develop/exist-versioning-release.md#versioning-scheme) of the current eXist-db release. So for exist-db version `3.x.x` the documentation's version should be `3.y.y`. The minor and patch numbers remain independent of each other.
+
+You can find the EXPath Application Package (`.xar` file) for the release in the `/target` directory
+
+## Publishing the Release
+Release are published in two locations:
+
+6.  GitHub: Repo and [releases](https://github.com/eXist-db/documentation/releases)
+    -   commit and push as usual
+    -   maven should have automatically created a release tag, update it by copying the release notes from `xar-assembly.xml`
+    -   check to make sure that the latest `.xar` file is attached to the GitHub release
+
+7.  [exist-db.org](http://exist-db.org): App repo and documentation homepage
+    -   Inform the exist-db.org admins that the documentation app should be deployed on the server.
+    -   Add documentation app to the public application repository.