[RELEASE] 0.1.0

.gitignore

@@ -7,3 +7,5 @@ build/
 polyrepo-settings.gradle
 dev/
 docker-sources/
+**/site/
+docs/0.x/*

CHANGELOG.md

@@ -0,0 +1,9 @@
+Change Log
+==========
+
+## Version 0.1.0
+
+_2019-07-16_
+
+ *  Initial release.
+

README.md

@@ -1,5 +1,7 @@
 # Barber💈
 
+See the [project website][barber] for documentation and APIs.
+
 A type safe Kotlin JVM library for building up localized, fillable, themed documents using [Mustache](https://mustache.github.io) templating.
 
 # Why?
@@ -308,6 +310,19 @@ BarberMoney(Money(50_00), EN_US)
  )
 ```
 
+
+Releases
+--------
+
+Our [change log][changelog] has release history.
+
+```kotlin
+implementation("app.cash.barber:barber:0.1.0")
+```
+
+Snapshot builds are [available][snap].
+
+
 License
 --------
 
@@ -324,3 +339,7 @@ License
     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions and
     limitations under the License.
+
+ [barber]: https://cashapp.github.io/barber/
+ [changelog]: http://cashapp.github.io/barber/changelog/
+ [snap]: https://oss.sonatype.org/content/repositories/snapshots/

client/build.gradle → barber/build.gradle

@@ -1,3 +1,11 @@
+apply plugin: 'com.vanniktech.maven.publish'
+
+jar {
+  manifest {
+    attributes('Automatic-Module-Name': 'app.cash.barber')
+  }
+}
+
 dependencies {
   implementation dep.guava
   implementation dep.kotlinStdLib
@@ -20,9 +28,10 @@ jar {
   baseName = "client"
 }
 
-shadowJar {
-  exclude('module-info.class') // https://github.com/johnrengelman/shadow/issues/352
-  mergeServiceFiles()
-  zip64 true
-  classifier = null
+afterEvaluate { project ->
+  project.tasks.dokka {
+    outputDirectory = "$rootDir/docs/0.x"
+    outputFormat = 'gfm'
+  }
 }
+

barber/gradle.properties

@@ -0,0 +1,3 @@
+POM_ARTIFACT_ID=barber
+POM_NAME=barber
+POM_PACKAGING=jar

client/src/main/kotlin/app/cash/barber/BarberException.kt → barber/src/main/kotlin/app/cash/barber/BarberException.kt

@@ -7,7 +7,7 @@ package app.cash.barber
  * Example
  * |output field 'subject' uses 'totally_invalid_field' but 'RecipientReceipt' has no such field
  * |  {sender} sent you {totally_invalid_field}
- * |  valid fields are [sender, amount, cancelUrl, deposit_expected_at]
+ * |  valid fields are: sender, amount, cancelUrl, deposit_expected_at
  *
  * TODO make exceptions typed so the above example could be parsed by a client and show rich feedback
  *  for DocumentTemplate writers

build.gradle

@@ -13,7 +13,6 @@ buildscript {
     classpath dep.gradleBuildScan
     classpath dep.kotlinGradlePlugin
     classpath dep.junitGradlePlugin
-    classpath dep.shadowJarPlugin
     classpath dep.spotlessPlugin
     classpath dep.mavenPublishGradlePlugin
   }
@@ -26,11 +25,16 @@ buildScan {
   termsOfServiceAgree = 'yes'
 }
 
+allprojects {
+  group = GROUP
+  version = VERSION_NAME
+}
+
 subprojects {
   apply plugin: 'java'
   apply plugin: 'kotlin'
   apply plugin: 'org.junit.platform.gradle.plugin'
-  apply plugin: 'com.github.johnrengelman.shadow'
+  apply plugin: 'org.jetbrains.dokka'
   apply plugin: 'com.diffplug.gradle.spotless'
 
   buildscript {
@@ -42,7 +46,6 @@ subprojects {
     dependencies {
       classpath dep.kotlinGradlePlugin
       classpath dep.junitGradlePlugin
-      classpath dep.shadowJarPlugin
       classpath dep.mavenPublishGradlePlugin
     }
   }
@@ -51,6 +54,7 @@ subprojects {
     mavenCentral()
     jcenter()
   }
+
   compileKotlin {
     kotlinOptions {
       jvmTarget = "1.8"
@@ -79,6 +83,17 @@ subprojects {
     testImplementation dep.junitApi
     testRuntimeOnly dep.junitEngine
   }
+
+  // We have to set the dokka configuration after evaluation since the com.vanniktech.maven.publish
+  // plugin overwrites our dokka configuration on projects where it's applied.
+  afterEvaluate { p ->
+    p.tasks.dokka {
+      reportUndocumented = false
+      skipDeprecated = true
+      jdkVersion = 8
+    }
+  }
+
   test {
     useJUnitPlatform()
     testLogging {

deploy_website.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+
+# The website is built using MkDocs with the Material theme.
+# https://squidfunk.github.io/mkdocs-material/
+# It requires Python to run.
+# Install the packages with the following command:
+# pip install mkdocs mkdocs-material
+
+set -ex
+
+REPO="git@github.com:cashapp/barber.git"
+DIR=temp-clone
+
+# Delete any existing temporary website clone
+rm -rf $DIR
+
+# Clone the current repo into temp folder
+git clone $REPO $DIR
+
+# Move working directory into temp folder
+cd $DIR
+
+# Generate the API docs
+./gradlew \
+  :barber:dokka
+
+# Copy in special files that GitHub wants in the project root.
+cat README.md | grep -v 'project website' > docs/index.md
+cp CHANGELOG.md docs/changelog.md
+
+# Build the site and push the new files up to GitHub
+mkdocs gh-deploy
+
+# Delete our temp folder
+cd ..
+rm -rf $DIR

docs/css/app.css

@@ -0,0 +1,48 @@
+@font-face {
+    font-family: cash-market;
+    src: url("https://cash-f.squarecdn.com/static/fonts/cash-market/v2/CashMarket-Regular.woff2") format("woff2");
+    font-weight: 400;
+    font-style: normal
+}
+
+@font-face {
+    font-family: cash-market;
+    src: url("https://cash-f.squarecdn.com/static/fonts/cash-market/v2/CashMarket-Medium.woff2") format("woff2");
+    font-weight: 500;
+    font-style: normal
+}
+
+@font-face {
+    font-family: cash-market;
+    src: url("https://cash-f.squarecdn.com/static/fonts/cash-market/v2/CashMarket-Bold.woff2") format("woff2");
+    font-weight: 700;
+    font-style: normal
+}
+
+body, input {
+    font-family: cash-market,"Helvetica Neue",helvetica,sans-serif;
+}
+
+.md-typeset h1, .md-typeset h2, .md-typeset h3, .md-typeset h4 {
+    font-family: cash-market,"Helvetica Neue",helvetica,sans-serif;
+    line-height: normal;
+    font-weight: bold;
+    color: #353535;
+}
+
+button.dl {
+  font-weight: 300;
+  font-size: 25px;
+  line-height: 40px;
+  padding: 3px 10px;
+  display: inline-block;
+  border-radius: 6px;
+  color: #f0f0f0;
+  margin: 5px 0;
+  width: auto;
+}
+
+.logo {
+  text-align: center;
+  margin-top: 150px;
+}

docs/releasing.md

@@ -0,0 +1,75 @@
+Releasing
+=========
+
+1. Update `CHANGELOG.md`.
+
+2. Set versions:
+
+    ```
+    export RELEASE_VERSION=X.Y.Z
+    export NEXT_VERSION=X.Y.Z-SNAPSHOT
+    ```
+
+3. Update, build, and upload:
+
+    ```
+    sed -i "" \
+      "s/VERSION_NAME=.*/VERSION_NAME=$RELEASE_VERSION/g" \
+      gradle.properties
+    sed -i "" \
+      "s/\"app.cash.barber:\([^\:]*\):[^\"]*\"/\"app.cash.barber:\1:$RELEASE_VERSION\"/g" \
+      `find . -name "README.md"`
+    ./gradlew clean uploadArchives
+    ```
+
+4. Visit [Sonatype Nexus](https://oss.sonatype.org/) to promote (close then release) the artifact. Or drop it if there is a problem!
+
+5. Tag the release, prepare for the next one, and push to GitHub.
+
+    ```
+    git commit -am "Prepare for release $RELEASE_VERSION."
+    git tag -a barber-$RELEASE_VERSION -m "Version $RELEASE_VERSION"
+    sed -i "" \
+      "s/VERSION_NAME=.*/VERSION_NAME=$NEXT_VERSION/g" \
+      gradle.properties
+    git commit -am "Prepare next development version."
+    git push && git push --tags
+    ```
+
+
+Prerequisites
+-------------
+
+Generate a GPG key (RSA, 4096 bit, 3650 day) expiry, or use an existing one.
+```
+$ gpg --full-generate-key 
+```
+
+Upload the GPG keys to public servers
+
+```
+$ gpg --list-keys --keyid-format LONG
+/Users/johnbarber/.gnupg/pubring.kbx
+------------------------------
+pub   rsa4096/XXXXXXXXXXXXXXXX 2019-07-16 [SC] [expires: 2029-07-13]
+      YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
+uid           [ultimate] John Barber <jbarber@cash.app>
+sub   rsa4096/ZZZZZZZZZZZZZZZZ 2019-07-16 [E] [expires: 2029-07-13]
+
+$ gpg --send-keys --keyserver keyserver.ubuntu.com XXXXXXXXXXXXXXXX
+```
+
+In `~/.gradle/gradle.properties`, set the following:
+
+ * `SONATYPE_NEXUS_USERNAME` - Sonatype username for releasing to `app.cash`.
+ * `SONATYPE_NEXUS_PASSWORD` - Sonatype password for releasing to `app.cash`.
+ * `signing.keyId` - key ID for GPG key. Example: `1A2345F8`. Get with the following command: 
+   ```
+   $ gpg --list-keys --keyid-format SHORT
+   ```
+ * `signing.password` - password for GPG key, recommended to be empty.
+ * `signing.secretKeyRingFile` - absoluate file path for `secring.gpg`. Example: `/Users/johnbarber/.gnupg/secring.gpg`.
+   * You may need to export this file manually with the following command where `XXXXXXXX` is the same `keyId` as above:
+     ```
+     $ gpg --keyring secring.gpg --export-secret-key XXXXXXXX > ~/.gnupg/secring.gpg
+     ```

gradle.properties

@@ -1,16 +1,16 @@
-GROUP=app.cash.barber
-VERSION_NAME=
+org.gradle.jvmargs='-Dfile.encoding=UTF-8'
 
+GROUP=app.cash.barber
+VERSION_NAME=1.0.0-SNAPSHOT
 
 POM_URL=https://github.com/cashapp/barber/
 POM_SCM_URL=https://github.com/cashapp/barber/
-POM_SCM_CONNECTION=scm:git:git://github.com/cashapp/barber.git
+POM_SCM_CONNECTION=scm:git:https://github.com/cashapp/barber.git
 POM_SCM_DEV_CONNECTION=scm:git:ssh://git@github.com/cashapp/barber.git
 
 POM_LICENCE_NAME=The Apache Software License, Version 2.0
 POM_LICENCE_URL=http://www.apache.org/licenses/LICENSE-2.0.txt
 POM_LICENCE_DIST=repo
 
 POM_DEVELOPER_ID=square
-POM_DEVELOPER_NAME=Square, Inc.
-
+POM_DEVELOPER_NAME=Square, Inc.

mkdocs.yml

@@ -0,0 +1,46 @@
+site_name: Barber
+repo_name: Barber
+repo_url: https://github.com/cashapp/barber
+site_description: "A Barber"
+site_author: Square, Inc.
+remote_branch: gh-pages
+
+copyright: 'Copyright © 2019 Square, Inc.'
+
+theme:
+  name: 'material'
+  favicon: img/favicon.ico
+  logo: img/cashapp.png
+  feature:
+    tabs: false
+  palette:
+    primary: 'grey'
+    accent: 'green'
+
+extra_css:
+  - 'css/app.css'
+
+markdown_extensions:
+  - smarty
+  - codehilite:
+      guess_lang: false
+  - footnotes
+  - meta
+  - toc:
+      permalink: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - tables
+
+nav:
+  - 'Overview': index.md
+  - 'Stack Overflow ⏏': https://stackoverflow.com/questions/tagged/barber?sort=active
+  - '0.x API': 0.x/barber/app/cash/barber/index.md
+  - 'Change Log': changelog.md
+  - 'Releasing': releasing.md
+

settings.gradle

@@ -1 +1 @@
-include 'client'
+include 'barber'