Tweak java contributor instructions for developing against local changes.
Change-Id: I1c8c8838a93c9a26d0caa93d61a53557205fba1e
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 707e415..0d8e3e5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -25,8 +25,9 @@
## Testing changes
Typical users of the Vanadium for Java libraries will use a dependency manager
-such as Maven or Gradle to bring Vanadium into their projects. For example, in
-an Android project, the user may do something like:
+such as Maven or Gradle to bring Vanadium into their projects.
+
+For example, in an Android project, the user may do something like:
```groovy
// MyAndroidProject/app/build.gradle
@@ -44,49 +45,94 @@
}
```
-In this example, using Gradle to build the application will cause a binary JAR
-version of Vanadium for Android to be downloaded from a Maven repository on the
-Internet (in this case, the JCenter repository). While this is very convenient
-for the end user, it is not so convenient to the Vanadium contributor who wishes
-to test some changes without making a full release.
+Using Gradle to build the application will cause a binary JAR version of
+Vanadium for Android to be downloaded from a Maven repository on the
+Internet (in this case, the JCenter repository).
-To get around this, we make use of the fact that Maven can be configured to use
-a repository on the local filesystem. Gradle gives us convenient access to this
-repository under the `mavenLocal` moniker. In order to publish to the local
-Maven repository, you will:
+While this is very convenient for the end user, it is not so convenient to the
+Vanadium contributor who wishes to test changes without making a full
+release.
-1. change `lib/build.gradle`, set `releaseVersion` to something that is not in
- use (e.g. '9.9')
-2. in the Java root directory, run `./gradlew :lib:clean
- :lib:publishToMavenLocal`
-3. if you wish to test changes to the Vanadium for Android library, repeat the
- above steps for the `android-lib` project (i.e. change
- `android-lib/build.gradle` and run `./gradlew :android-lib:clean
- :android-lib:publishToMavenLocal`). Ensure that the `releaseVersion`
- variables in the two `build.gradle` files are the same.
+To be able to incorporate local changes to underlying libraries, we
+make use of the fact that Maven can be configured to use a repository
+on the local filesystem.
+[Gradle configuration](http://developer.android.com/tools/building/configuring-gradle.html)
+gives us convenient access to this repository under the `mavenLocal`
+moniker.
-Now that the library is published, you can modify the example Android app's
-`build.gradle` as follows:
+The following instructions do that, and assume you work from the Java
+root directory, e.g.
-```groovy
-// MyAndroidProject/app/build.gradle
-
-apply plugin: 'com.android.application'
-
-// ...
-
-repositories {
- mavenLocal() // <-- This must come first, repositories are searched
- // in the order they appear in this file.
- jCenter()
-}
-
-dependencies {
- compile 'io.v:vanadium-android:9.9' // Set this to the releaseVersion
- // you chose above.
-}
+```
+cd ~/vanadium/release/java
```
-Importantly, you can re-run step 2 above as many times as you like without
-having to choose a new `releaseVersion`.
+#### Modify Go library construction
+
+Edit
+
+```
+lib/build.gradle
+```
+
+Set `releaseVersion` to a new unused value, e.g. `9.9`.
+
+
+#### Modify android library construction
+
+Edit
+
+```
+android-lib/build.gradle
+```
+
+ 1. Set `releaseVersion` to the same value used above.
+ 2. Add `mavenLocal()` before `jCenter()` in the `buildscript` stanzas.
+
+
+#### Modify project construction
+
+Edit
+
+```
+${yourProject}/build.gradle # project level
+```
+
+Add `mavenLocal()` _before_ `jCenter()` in the
+`allprojects/repositories` stanza.
+
+
+#### Modify module construction
+
+Edit
+
+```
+${yourProject}/app/build.gradle # module level
+```
+
+Change the `dependencies` stanza to specify your new version number, e.g.
+
+```
+compile 'io.v:vanadium-android:9.9'
+```
+
+#### Purge caches
+
+```
+./gradlew :lib:clean :android-lib:clean
+```
+
+#### Deploy locally
+
+```
+./gradlew :lib:publishToMavenLocal :android-lib:publishToMavenLocal
+```
+
+You can now build your project against local
+upstrean changes, e.g.
+
+```
+(cd ${yourProject}; ./gradlew assembleDebug)
+```
+
