Update sbt build for akka.io (#583)

RELEASING.md

@@ -1,21 +1,30 @@
 # Releasing
 
-1. Update the version number in the `akka-grpc-xx-stable` project name in the [whitesource web UI](https://saas.whitesourcesoftware.com)
-    - For example you'd call the project `akka-grpc-0.2-stable`
-1. Create a [new release](https://github.com/akka/akka-grpc/releases/new) with the next tag version (e.g. `v0.2`), title and release description including notable changes mentioning external contributors.
-1. Travis CI will start a [CI build](https://travis-ci.org/akka/akka-grpc/builds) for the new tag and publish:
-  - SBT Plugin is published to [Bintray](https://bintray.com/akka/sbt-plugin-releases) that is linked the SBT plugins repo (no further steps required) 
-  - Gradle plugin directly to the Gradle plugin portal (no further steps required)
-  - Library jars to [Bintray](https://bintray.com/akka/maven) that needs to be synced with Maven Central
-1. [Sync](https://bintray.com/akka/maven/akka-grpc/_latestVersion#central) from Bintray to Maven Central
-
-Due to https://github.com/akka/akka-grpc/issues/365, when the tag is created
-before that commit has been been successfully built for the 'master' branch,
-the maven tests for the build of the 'master' branch will fail for that
-commit. The release build and the next commit on 'master' should be fine.
+Create a new issue from the [Release Train Issue Template](docs/release-train-issue-template.md) and follow the steps.
 
 ## Gradle plugin release details
 
 The Gradle plugin goes directly to the Gradle Plugin Portal. An encrypted `gradle.properties` that includes a
 publishing key and password is checked in under `gradle.properties.enc` and is decrypted by a private key known
 only to [travis](https://docs.travis-ci.com/user/encrypting-files/).
+
+### Releasing only updated docs
+
+It is possible to release a revised documentation to the already existing release.
+
+1. Create a new branch from a release tag. If a revised documentation is for the `v0.3` release, then the name of the new branch should be `docs/v0.3`.
+1. Add and commit `version.sbt` file that pins the version to the one, that is being revised. Also set `isSnapshot` to `false` for the stable documentation links. For example:
+    ```scala
+    ThisBuild / version := "0.6.1"
+    ThisBuild / isSnapshot := false
+    ```
+1. Make all of the required changes to the documentation.
+1. Build documentation locally with `CI` settings:
+    ```sh
+    env CI=true sbt akka-grpc-docs/previewSite
+    ```
+1. If the generated documentation looks good, send it to Gustav:
+    ```sh
+    env CI=true sbt akka-grpc-docs/publishRsync
+    ```
+1. Do not forget to push the new branch back to GitHub.

build.sbt

@@ -135,23 +135,34 @@ lazy val docs = Project(
   // Make sure code generation is ran:
   .dependsOn(pluginTesterScala)
   .dependsOn(pluginTesterJava)
-  .enablePlugins(AkkaParadoxPlugin)
+  .enablePlugins(AkkaParadoxPlugin, ParadoxSitePlugin, PublishRsyncPlugin)
   .settings(
-    skip in publish := true,
+    name := "Akka gRPC",
+    publish / skip := true,
+    whitesourceIgnore := true,
+    previewPath := (Paradox / siteSubdirName).value,
+    Paradox / siteSubdirName := s"docs/akka-grpc/${if (isSnapshot.value) "snapshot" else version.value}",
     // Make sure code generation is ran before paradox:
     (Compile / paradox) := ((Compile / paradox) dependsOn (Compile / compile)).value,
-    Compile / paradoxGroups := Map(
+    paradoxGroups := Map(
       "Language" -> Seq("Java", "Scala"),
       "Buildtool" -> Seq("sbt", "Gradle", "Maven"),
     ),
     Compile / paradoxProperties ++= Map(
-      "grpc.version" → Dependencies.Versions.grpc,
-      "project.url" -> "https://developer.lightbend.com/docs/akka-grpc/current/",
-      "canonical.base_url" -> "https://developer.lightbend.com/docs/akka-grpc/current/",
-      "akka-http.version" → Dependencies.Versions.akkaHttp,
+      "akka.version" -> Dependencies.Versions.akka,
+      "akka-http.version" -> Dependencies.Versions.akkaHttp,
+      "grpc.version" -> Dependencies.Versions.grpc,
+      "project.url" -> "https://doc.akka.io/docs/akka-grpc/current/",
+      "canonical.base_url" -> "https://doc.akka.io/docs/akka-grpc/current",
+      "scaladoc.scala.base_url" -> s"https://www.scala-lang.org/api/current/",
+      "extref.akka.base_url" -> s"https://doc.akka.io/docs/akka/${Dependencies.Versions.akka}/%s",
+      "scaladoc.akka.base_url" -> s"https://doc.akka.io/api/akka/${Dependencies.Versions.akka}",
       "extref.akka-http.base_url" -> s"https://doc.akka.io/docs/akka-http/${Dependencies.Versions.akkaHttp}/%s",
+      "scaladoc.akka.http.base_url" -> s"https://doc.akka.io/api/akka-http/${Dependencies.Versions.akkaHttp}/",
     ),
     resolvers += Resolver.jcenterRepo,
+    publishRsyncArtifact := makeSite.value -> "www/",
+    publishRsyncHost := "akkarepo@gustav.akka.io"
   )
 
 lazy val pluginTesterScala = Project(

docs/release-train-issue-template.md

@@ -0,0 +1,67 @@
+# Release Train Issue Template for Akka gRPC
+
+(Liberally copied and adopted from Scala itself https://github.com/scala/scala-dev/blob/b11cd2e4a4431de7867db6b39362bea8fa6650e7/notes/releases/template.md)
+
+For every release, make a copy of this file named after the release, and expand the variables.
+Ideally replacing variables could become a script you can run on your local machine.
+
+Variables to be expanded in this template:
+- $AKKA_GRPC_VERSION$=??? 
+
+### before the release
+
+- [ ] Check that any new `deprecated` annotations use the correct version name
+- [ ] Check that open PRs and issues assigned to the milestone are reasonable
+- [ ] Decide on planned release date
+- [ ] Notify depending projects (Akka, Play, Lagom) about the upcoming release
+- [ ] Create a new milestone for the [next version](https://github.com/akka/akka-grpc/milestones)
+- [ ] Check [closed issues without a milestone](https://github.com/akka/akka-grpc/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20no%3Amilestone) and either assign them the 'upcoming' release milestone or `invalid/not release-bound`
+- [ ] Make sure all important / big PRs have been merged by now
+- [ ] Communicate that a new version is about to be released in [Gitter Akka Dev Channel](https://gitter.im/akka/dev), so that no new Pull Requests are merged
+
+### Preparing release notes in the documentation / announcement
+
+- [ ] For non-patch releases: rename the 'akka-grpc-x.x-stable' and 'akka-grpc-supported-x.x-stable' reporting projects in [WhiteSource](https://saas.whitesourcesoftware.com/Wss/WSS.html) accordingly (unfortunately this requires permissions that cannot be shared outside of Lightbend)
+- [ ] Prepare release notes listing contributors generated by [`sbt-authors`](https://github.com/2m/authors) (eg. `sbt authors v0.22 HEAD`)
+- [ ] For non-patch releases: Create a news item draft PR on [akka.github.com](https://github.com/akka/akka.github.com), using the milestone
+- [ ] Move all [unclosed issues](https://github.com/akka/akka-grpc/issues?q=is%3Aopen+is%3Aissue+milestone%3A$AKKA_GRPC_VERSION$) for this milestone to the next milestone
+
+### Cutting the release
+
+- [ ] Wait until [master build finished](https://travis-ci.org/akka/akka-grpc/builds/) after merging the release notes
+- [ ] Create a [new release](https://github.com/akka/akka-grpc/releases/new) with the next tag version `v$AKKA_GRPC_VERSION$`, title and release description
+- [ ] Check that Travis CI release build has executed successfully (Travis will start a [CI build](https://travis-ci.org/akka/akka-grpc/builds) for the new tag and publish artifacts to Bintray and documentation to Gustav)
+- [ ] Go to [Bintray](https://bintray.com/akka/maven/akka-grpc) and select the just released version
+- [ ] Go to the Maven Central tab, check the *Close and release repository when done* checkbox and sync with Sonatype (using your Sonatype TOKEN key and password)
+
+### Check availability
+
+- [ ] Check [reference](https://doc.akka.io/docs/akka-grpc/$AKKA_GRPC_VERSION$/) documentation
+- [ ] Check the release on [Maven central](http://central.maven.org/maven2/com/lightbend/akka/grpc/akka-grpc-scalapb-protoc-plugin_2.12/$AKKA_GRPC_VERSION$/)
+
+### When everything is on maven central
+  - [ ] Log into `gustav.akka.io` as `akkarepo` 
+    - [ ] update the `current` links on `repo.akka.io` to point to the latest version with
+         ```
+         ln -nsf $AKKA_GRPC_VERSION$ www/docs/akka-grpc/current
+         ```
+    - [ ] check changes and commit the new version to the local git repository
+         ```
+         cd ~/www
+         git add docs/akka-grpc/current docs/akka-grpc/$AKKA_GRPC_VERSION$
+         git commit -m "Akka gRPC $AKKA_GRPC_VERSION$"
+         ```
+
+### Announcements
+
+- [ ] For non-patch releases: Merge draft news item for [akka.io](https://github.com/akka/akka.github.com)
+- [ ] Send a release notification to [Lightbend discuss](https://discuss.akka.io)
+- [ ] Tweet using the akkateam account (or ask someone to) about the new release
+- [ ] Announce on [Gitter akka/akka](https://gitter.im/akka/akka)
+- [ ] Announce internally
+
+### Afterwards
+
+- [ ] Update version for [Lightbend Supported Modules](https://developer.lightbend.com/docs/reactive-platform/2.0/supported-modules/#other-akka-modules) in [private project](https://github.com/lightbend/reactive-platform-docs/blob/master/build.sbt)
+- [ ] Close the [$AKKA_GRPC_VERSION$ milestone](https://github.com/akka/akka-grpc/milestones?direction=asc&sort=due_date)
+- Close this issue

project/plugins.sbt

@@ -7,6 +7,8 @@ addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.14.9")
 addSbtPlugin("com.eed3si9n" % "sbt-buildinfo" % "0.9.0")
 addSbtPlugin("net.virtual-void" % "sbt-dependency-graph" % "0.9.0")
 addSbtPlugin("com.lightbend.akka" % "sbt-paradox-akka" % "0.18")
+addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "1.4.0")
+addSbtPlugin("com.lightbend.sbt" % "sbt-publish-rsync" % "0.1")
 addSbtPlugin("io.spray" % "sbt-revolver" % "0.9.1")
 addSbtPlugin("com.lightbend" % "sbt-whitesource" % "0.1.14")
 addSbtPlugin("com.typesafe.sbt" % "sbt-git" % "1.0.0")