#57 more docs

tobyweston · May 8, 2018 · a72e44f · a72e44f
1 parent 13666c7
commit a72e44f
Show file tree

Hide file tree

Showing 4 changed files with 142 additions and 35 deletions.
diff --git a/site/src/main/resources/microsite/data/menu.yml b/site/src/main/resources/microsite/data/menu.yml
@@ -29,6 +29,12 @@ options:
   - title: Hacking
     url: docs/hacking.html
 
+    nested_options:
+     - title: SBT Plugins
+       url: docs/hacking/sbt_plugins.html
+     - title: Releasing
+       url: docs/hacking/release.html
+
   - title: Ansible Automation
     url: docs/ansible.html
     section: ansible

diff --git a/site/src/main/tut/docs/hacking.md b/site/src/main/tut/docs/hacking.md
@@ -7,6 +7,8 @@ title: Hacking
 
 Aka the `DEVELOPERS` readme, if you want to get your hands dirty with the code, this is the section for you.
 
+1. See the [SBT Plugins](hacking/sbt_plugins.html) for an overview of the SBT plugins we use
+1. See the [release](hacking/release.html) instructions on how to release
 
 ## Quick Start (in an IDE)
 
@@ -19,7 +21,7 @@ Check the web page with [http://localhost:11900](http://localhost:11900).
 
 ## Build the Web App
 
-The front-end is hosting in another project, [https://github.com/tobyweston/temperature-machine-ui](https://github.com/tobyweston/temperature-machine-ui). Development goes on over there but when it's ready to bring into the temperature-machine, run the following script.
+The front-end is hosted in another project, [https://github.com/tobyweston/temperature-machine-ui](https://github.com/tobyweston/temperature-machine-ui). Development goes on over there but when it's ready to bring into the temperature-machine, run the following script.
 
     build-webapp.sh
 
@@ -28,41 +30,8 @@ It will download the latest version of the web-app, build it and overwrite the c
 The `resources` folder is statically served by `Server.scala`.
 
 
-## Build Deployment JAR
 
-Run the following to produce the `temperature-machine-2.1.jar` file.
-
-    sbt assembly
-
-
-## Plugins
-
-### sbt-scoverage
-
-Run the following to get an idea of test coverage.
-
-    sbt clean coverage test coverageReport
-
-Check out the generated report under `target/scala-2.12/scoverage-report`. Remember good coverage doesn't always mean good tests!
-
-
-### sbt-assembly
-
-See [Build Deployment JAR](#build-deployment-jar) section above.
-
-
-### sbt-microsite
-
-Run `sbt site/makeMicrosite` to create the site you're reading now. Find it in `site/target/jekyll` once built.
-
-You should be able to preview the site using Jekyll to serve it.
-
-    $ cd site/target/jekyll
-    $ jekyll serve
-
-If you're going to publish it (`sbt site/publishMicrosite`), make sure you `site/makeMicrosite` first (otherwise you'll see a commit on the [`gh-pages`](https://github.com/tobyweston/temperature-machine/commit/7aa09f7612f3ff38d86de9ab6ae2fe6ba03223c0) branch with `0 commits`)
-
-## Scalaz vs. Cats
+## Scalaz vs. Cats Notes
 
 We started with Scalaz but the latest version of Http4s prefers Cats. The break apart of Scalaz to FS2 etc all seems a bit complicated, so I've captured some notes below.
 

diff --git a/site/src/main/tut/docs/hacking/release.md b/site/src/main/tut/docs/hacking/release.md
@@ -0,0 +1,44 @@
+---
+layout: docs
+title: Contributing
+---
+
+# Release Overview
+
+The general process is perhaps a little unconventional, we have three elements to consider.
+
+1. The [backend](http://github.com/tobyweston/temperature-machine) / server code (Scala)
+1. The [front-end](http://github.com/tobyweston/temperature-machine-ui) / UI (JavaScript)
+1. The [debian package](http://robotooling.com/debian/) available via `apt-get`
+
+Each is managed separately but should be consistent in terms of the release artifacts.
+
+To do this, we:
+
+1. Tag and release from the backend project using the `sbt-release` plugin and [Github releases](https://github.com/tobyweston/temperature-machine/releases)
+1. As the UI project is copied into the backend project as JavaScript assets (using `build-webapp.sh`), the UI project is not tagged or released via Github
+1. After tagging, immediately run `release-debian-package.sh` to publish the tagged version to the debian repository
+
+## Versioning
+
+The software is released using a major/minor number scheme with a Git SHA postfix. For example:
+
+    $ temperature-machine -- -v
+    temperature-machine 2.1 (56add8)
+
+SHA updates are generally used to get small increments out without the overhead of a "proper" release.
+
+
+# Releasing
+
+## Tag and Release
+
+To do release, run the following
+
+    sbt release
+
+This would usually prepare a JAR, tag and copy the JAR to a local maven repo. We're not interested in publishing the JAR via a Maven repository, instead we want to create a Debian package and publish that.
+
+
+## Debian Package
+
diff --git a/site/src/main/tut/docs/hacking/sbt_plugins.md b/site/src/main/tut/docs/hacking/sbt_plugins.md
@@ -0,0 +1,88 @@
+---
+layout: docs
+title: SBT
+---
+
+# SBT
+
+An overview of the plugins we use and what they do (they are defined in `plugins.sbt`).
+
+## sbt-buildinfo
+
+<p class="bg-warning">
+Configured in <code>version.sbt</code>.
+</p>
+
+Auto-generates classes containing the major/minor version number plus the current Git SHA and makes it available in the code.
+
+
+## sbt-scoverage
+
+Run the following to get an idea of test coverage.
+
+    sbt clean coverage test coverageReport
+
+Check out the generated report under `target/scala-2.12/scoverage-report`. Remember good coverage doesn't always mean good tests!
+
+## sbt-release 
+
+<p class="bg-warning">
+Configured in <code>release.sbt</code>.
+</p>
+
+Used minimally as a convenience to tag a release.
+
+
+## sbt-assembly
+
+<p class="bg-warning">
+Configured in <code>assembly.sbt</code>.
+</p>
+
+The Assembly plugin will generate a "fat" jar. Run:
+
+    sbt assembly
+
+...to create (for example) `target/`.
+
+
+## sbt-native-packager
+
+<p class="bg-warning">
+Configured in <code>package.sbt</code>.
+</p>
+
+The Native Packager plugin will take the output of the [Assembly](#sbt-assembly) plugin and package it up as a deployment artifact. In our case, this takes the form of a Debian package (`.deb`) that can be installed via `dpkg` and `apt-get` on the Raspberry Pi.
+
+To prepare a package, run the following:
+
+    sbt debian:packageBin
+
+To perform a traditional "release", see the [Release](release.html) section.
+
+
+## sbt-proguard
+
+<p class="bg-warning">
+Configured in <code>proguard.sbt</code>.
+</p>
+
+
+We use the Proguard plugin purely to reduce the file size of the deployment artifact. It reduces the ~50MB artifact to around 10MB, which is pretty cool.
+
+
+## sbt-microsite
+
+<p class="bg-warning">
+Configured in <code>site.sbt</code>.
+</p>
+
+Run `sbt site/makeMicrosite` to create the site you're reading now. Find it in `site/target/jekyll` once built.
+
+You should be able to preview the site using Jekyll to serve it.
+
+    $ cd site/target/jekyll
+    $ jekyll serve
+
+If you're going to publish it (`sbt site/publishMicrosite`), make sure you `site/makeMicrosite` first (otherwise you'll see a commit on the [`gh-pages`](https://github.com/tobyweston/temperature-machine/commit/7aa09f7612f3ff38d86de9ab6ae2fe6ba03223c0) branch with `0 commits`)
+