From 574139665aace0d46e19478ca7b21f8fc11f82fd Mon Sep 17 00:00:00 2001
From: Kevin Oliver <koliver@twitter.com>
Date: Wed, 7 Sep 2016 16:43:15 +0000
Subject: [PATCH] Update docs on contributing

Problem / Solution

The docs for contributions have gotten a bit out of date and were in
need of some touchups.

RB_ID=868780
---
 CONTRIBUTING.md | 40 +++++++++++++++++++++++++++++++---------
 README.md       |  8 ++++++++
 sbt             |  4 ++--
 3 files changed, 41 insertions(+), 11 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7f67489b..1d980a8f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,16 +7,13 @@ We'd love to get patches from you!
 We are not currently publishing snapshots for TwitterServer's dependencies, which
 means that it may be necessary to publish the `develop` branches of these
 libraries locally in order to work on TwitterServer's `develop` branch. To do so
-you can run `./bin/travisci` script and pass it an optional
-`TRAVIS_SCALA_VERSION` environment variable. For example, the following command
-locally publishes all the TwitterServer dependencies built for Scala 2.11.7.
+you can use our build tool, [dodo](https://github.com/twitter/dodo).
 
-```
-TRAVIS_SCALA_VERSION=2.11.7 ./bin/travisci
+``` bash
+curl -s https://raw.githubusercontent.com/twitter/dodo/develop/bin/build | bash -s -- --no-test twitter-server
 ```
 
-We are planning to begin publishing snapshots soon, which will make these steps
-unnecessary. If you have any questions or run into any problems, please create
+If you have any questions or run into any problems, please create
 an issue here, tweet at us at [@finagle](https://twitter.com/finagle), or email
 the Finaglers mailing list.
 
@@ -57,6 +54,31 @@ Travis CI more useful for development, but for now you don't need to worry if
 it's failing (assuming that you are able to build and test your changes
 locally).
 
+## Compatibility
+
+We try to keep public APIs stable for the obvious reasons. Often,
+compatibility can be kept by adding a forwarding method. Note that we
+avoid adding default arguments because this is not a compatible change
+for our Java users.  However, when the benefits outweigh the costs, we
+are willing to break APIs. The break should be noted in the Breaking
+API Changes section of the [changelog](CHANGES). Note that changes to
+non-public APIs will not be called out in the [changelog](CHANGES).
+
+## Java
+
+While the project is written in Scala, its public APIs should be usable from
+Java. This occasionally works out naturally from the Scala interop, but more
+often than not, if care is not taken Java users will have rough corners
+(e.g. `SomeCompanion$.MODULE$.someMethod()` or a symbolic operator).
+We take a variety of approaches to minimize this.
+
+1. Add a "compilation" unit test, written in Java, that verifies the APIs are
+   usable from Java.
+2. If there is anything gnarly, we add Java adapters either by adding
+   a non-symbolic method name or by adding a class that does forwarding.
+3. Prefer `abstract` classes over `traits` as they are easier for Java
+   developers to extend.
+
 ## Style
 
 We generally follow [Effective Scala][es] and the [Scala Style Guide][ssg]. When
@@ -166,8 +188,8 @@ simplest solution is to create a symbolic link to `sphinx-build2` named
 `sphinx-build` somewhere on your path.
 
 Please note that any additions or changes to the API must be thoroughly
-described in [ScalaDoc][8] comments. We will also happily consider pull
-requests that improve the existing ScalaDocs!
+described in [Scaladoc][8] comments. We will also happily consider pull
+requests that improve the existing Scaladocs!
 
 [0]: https://github.com/twitter/finagle/pull/267
 [1]: https://github.com/twitter/twitter-server/issues?direction=desc&labels=Starter&sort=created&state=open
diff --git a/README.md b/README.md
index 8a5b8010..e92bc387 100644
--- a/README.md
+++ b/README.md
@@ -20,11 +20,19 @@ and is being actively developed and maintained.
 
 Browse the [user guide](https://twitter.github.io/twitter-server/).
 
+## Releases
+
+[Releases](https://maven-badges.herokuapp.com/maven-central/com.twitter/twitter-server_2.11)
+are done on an approximately monthly schedule. While [semver](http://semver.org/)
+is not followed, the [changelogs](CHANGES) are detailed and include sections on
+public API breaks and changes in runtime behavior.
+
 ## Getting involved
 
 * Website: https://twitter.github.io/twitter-server/
 * Source: https://github.com/twitter/twitter-server/
 * Mailing List: [finaglers@googlegroups.com](https://groups.google.com/forum/#!forum/finaglers)
+* Chat: https://gitter.im/twitter/finagle
 
 ## Contributing
 
diff --git a/sbt b/sbt
index 11206745..360eb77c 100755
--- a/sbt
+++ b/sbt
@@ -7,7 +7,7 @@ sbtsha128=1de48c2c412fffc4336e4d7dee224927a96d5abc
 sbtrepo=http://repo.typesafe.com/typesafe/ivy-releases/org.scala-sbt/sbt-launch
 
 if [ ! -f $sbtjar ]; then
-  echo "downloading $sbtjar" 1>&2
+  echo "downloading $PWD/$sbtjar" 1>&2
   if ! curl --location --silent --fail --remote-name $sbtrepo/$sbtver/$sbtjar; then
     exit 1
   fi
@@ -15,7 +15,7 @@ fi
 
 checksum=`openssl dgst -sha1 $sbtjar | awk '{ print $2 }'`
 if [ "$checksum" != $sbtsha128 ]; then
-  echo "bad $sbtjar.  delete $sbtjar and run $0 again."
+  echo "bad $PWD/$sbtjar.  delete $PWD/$sbtjar and run $0 again."
   exit 1
 fi