L4: Add JRuby Support

L4.md

@@ -0,0 +1,77 @@
+Title
+----
+* Author(s): Jason Lunn <jason@jungroup.com>
+* Approver: a11r
+* Status: Draft
+* Implemented in: Ruby
+* Last updated: 2017-02-14
+* Discussion at: https://github.com/grpc/grpc/issues/6705
+
+## Abstract
+
+Add first class support for the JRuby interpreter by publishing a variant of the gem targeted to the `java` platform.
+
+## Background
+
+Dependency management for Ruby packages ("gems") relies on the availability of variant builds published to
+[RubyGems.org](https://rubygems.org/) that declare what platform they target. Today, the `grpc` gem is already
+supporting [five variants](https://rubygems.org/gems/grpc/versions) for every released version: `x64-mingw32`,
+`x86_64-linux`, `universal-darwin`, `x86-mingw32`, in addition to a variant with no explicit platform.
+
+As detailed in [this issue](https://github.com/grpc/grpc/issues/6705), the [JRuby](http://jruby.org/) interpreter (which is built on top of
+the JVM) is not able to correctly resolve dependencies on the `grpc` gem because it attempts and fails to build a native
+extension that is implemented in C. While it possible on some versions of JRuby to make this approach work, it is much
+more common (especially when a Java client library exists) to create a variant of the gem that declares as its target
+the `java` platform and expose a JAR-based implementation through a Ruby wrapper. This is the approach taken in other
+Ruby client libraries maintained by Google, e.g.
+[Google Protobuf](https://github.com/google/protobuf/blob/master/ruby/google-protobuf.gemspec#L12).
+
+
+### Related Proposals: 
+* Not Applicable
+
+## Proposal
+
+1. Use [JBundler](https://github.com/mkristian/jbundler) or a comparable tool to facilitate expressing a dependency on
+the Maven artifact published by the `gprc-java` project, exposing the JAR file to the Ruby build process when running on
+JRuby.
+1. Extend the existing [Gemspec](https://github.com/grpc/grpc/blob/master/grpc.gemspec) to add conditional logic that
+both includes the JAR file and any necessary wrapper code and excludes C implementation files when run on JRuby.
+1. Amend the standard gem release process to include publishing from the latest JRuby interpreter available at release
+time.
+
+## Rationale
+
+#### Using a native library vs creating a "pure" Ruby client
+A "pure" Ruby client with no dependency on a native library would work equally well on JRuby as other Ruby interpreters.
+It is assumed that the questions of whether the performance would suffer too greatly if it were not
+implemented in C and the maintenance burden of a completely standalone Ruby implementation are settled matters that were
+already discussed when the Ruby client was first implemented. Therefore this proposal does not suggest creating a "pure"
+Ruby implementation to address JRuby support.
+
+#### Creating a Maven dependency
+The current organization of GRPC's source code repositories creates a challenge that other projects that support a Ruby
+gem with dedicated support for clients running under JRuby do not have, namely that the Ruby source lives in a distinct
+project from the source of the Java client. This proposal suggests using Maven to solve the artifact dependency in order
+to avoid creating a requirement on a unified repository that includes the C, Ruby, and Java source in a single project.
+That approach works fine (this is how Google Protobuf handles the same problem), and might even be more optimal, but
+would require repository-level refactoring. The `grpc-java` client already exposes releases via Maven so there would be
+no work required on their part to support this proposal.
+
+## Implementation
+
+1. Update the Gemspec to add JBundler to the list of development dependencies when run on JRuby 
+1. Create a [JarFile](https://github.com/torquebox/maven-tools/wiki/Jarfile) to create a dependency on the grpc-java jar 
+1. Create wrapper code that delegates the existing Ruby API calls to the Java client, as needed
+1. Address any test regressions or expectation updates introduced by executing on JRuby
+1. Address any assumptions in documentation or code about the set of supported platforms, e.g. in the README for
+[`grpc-tools`](https://github.com/grpc/grpc/blob/master/src/ruby/tools/README.md)
+1. Update the release process tooling / and or documentation include JRuby specifics, as needed
+
+All points above except the last one can be community contributed. Project members would have to be responsible for the
+last point as it is not exposed in the repository itself.
+
+## Open issues
+
+1. Is there a more correct heuristic for picking the version of the Maven artifact than keeping it unpinned so that it
+selects the latest version available?