Updated README

Added short introduction to the README Updated maintainers and contributors Added build instructions Added Versioning section (inspired by a similar section in the README for RxJava). Added Binaries sections Added YourKit to list of supporters, updated text for IntelliJ to match.
mongodb · Jan 13, 2015 · 88cb015 · 88cb015
1 parent 75b8ea0
commit 88cb015
Showing 1 changed file with 103 additions and 22 deletions.
diff --git a/README.md b/README.md
@@ -1,12 +1,24 @@
-## MongoDB Java Driver ##
- * release notes: http://github.com/mongodb/mongo-java-driver/wiki/Release-Notes
- * driver home: http://github.com/mongodb/mongo-java-driver
- * mongodb home: http://www.mongodb.org/
- * javadoc: http://api.mongodb.org/java/
- * snapshot releases: https://oss.sonatype.org/content/repositories/snapshots/org/mongodb/mongo-java-driver/
+# MongoDB 3.x Java Driver
 
-Support / Feedback
-==================
+The 3.x MongoDB driver for Java is a major release.  The API is not yet stable, and while it is well-tested we do not yet consider it
+ready for a production deployment.  Hightlights include:
+
+* A generic MongoCollection interface that implements a new cross-driver CRUD specification.
+* A new asynchronous MongoClient API that can leverage either [Netty](http://netty.io/)
+or Java 7's [AsynchronousSocketChannel](http://docs.oracle.com/javase/7/docs/api/java/nio/channels/AsynchronousSocketChannel.html)
+* A new Codec infrastructure that you can use to build high-performance encoders and decoders without having to go through an intermediate
+Map.
+* A new core driver on top of which you can build alternative or experimental driver APIs
+
+## Release Notes
+
+Release notes are available [here](https://github.com/mongodb/mongo-java-driver/releases).
+
+## API Documentation:
+
+Javadoc for all major and minor releases is available [here](http://api.mongodb.org/java/).
+
+## Support / Feedback
 
 For issues with, questions about, or feedback for the MongoDB Java driver, please look into
 our [support channels](http://www.mongodb.org/about/support). Please
@@ -19,8 +31,7 @@ connectivity issues, it's often also useful to paste in the line of code where y
 along with the values of all parameters that you pass to the constructor. You should also check your application logs for
 any connectivity-related exceptions and post those as well.
 
-Bugs / Feature Requests
-=======================
+## Bugs / Feature Requests
 
 Think you’ve found a bug? Want to see a new feature in the Java driver? Please open a
 case in our issue management tool, JIRA:
@@ -31,29 +42,99 @@ case in our issue management tool, JIRA:
 
 Bug reports in JIRA for the driver and the Core Server (i.e. SERVER) project are **public**.
 
-Security Vulnerabilities
-------------------------
-
 If you’ve identified a security vulnerability in a driver or any other
 MongoDB project, please report it according to the [instructions here]
 (http://docs.mongodb.org/manual/tutorial/create-a-vulnerability-report).
 
-### Maintainers
+## Versioning
+
+Major increments (such as 2.x -> 3.x) will occur when break changes are being made to the public API.  All methods and
+classes removed in a major release will have been deprecated in a prior release of the previous major release branch, and/or otherwise
+called out in the release notes.
+
+Minor 3.x increments (such as 3.1, 3.2, etc) will occur when non-trivial new functionality is added or significant enhancements or bug
+fixes occur that may have behavioral changes that may affect some edge cases (such as dependence on behavior resulting from a bug). An
+example of an enhancement is a method or class added to support new functionality added to the MongoDB server.   Minor releases will
+almost always be binary compatible with prior minor releases from the same major release branch, exept as noted below.
+
+Patch 3.x.y increments (such as 3.0.0 -> 3.0.1, 3.1.1 -> 3.1.2, etc) will occur for bug fixes only and will always be binary compitible
+with prior patch releases of the same minor release branch.
+
+#### @Beta
+
+APIs marked with the `@Beta` annotation at the class or method level are subject to change. They can be modified in any way, or even
+removed, at any time. If your code is a library itself (i.e. it is used on the CLASSPATH of users outside your own control), you should not
+use beta APIs, unless you repackage them (e.g. by using shading, etc).
+
+#### @Deprecated
+
+APIs marked with the `@Deprecated` annotation at the class or method level will remain supported until the next major release but it is
+recommended to stop using them.
+
+#### com.mongodb.internal.*
+
+All code inside the `com.mongodb.internal.*` packages is considered private API and should not be relied upon at all. It can change at any
+time.
+
+## Binaries
+
+Binaries and dependency information for Maven, Gradle, Ivy and others can be found at
+[http://search.maven.org](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.mongodb%22%20AND%20a%3A%22mongo-java-driver%22).
+
+Example for Maven:
+
+```xml
+<dependency>
+    <groupId>org.mongodb</groupId>
+    <artifactId>mongodb-driver</artifactId>
+    <version>x.y.z</version>
+</dependency>
+```
+
+Snapshot builds are also published regulary via Sonatype.
+
+Example for Maven:
+
+```xml
+    <repositories>
+        <repository>
+            <id>sonatype-snapshot</id>
+            <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
+        </repository>
+    </repositories>
+```
+
+## Build
+
+To build the driver:
+
+```
+$ git clone https://github.com/mongodb/mongo-java-driver.git
+$ cd mongo-java-driver
+$ ./gradlew check
+```
+
+### Build status:
+
+[![Build Status](https://travis-ci.org/mongodb/mongo-java-driver.svg?branch=3.0.x)](https://travis-ci.org/mongodb/mongo-java-driver) | [![Build Status](https://jenkins.10gen.com/job/mongo-java-driver-3.0.x/badge/icon)](https://jenkins.10gen.com/job/mongo-java-driver-3.0.x/)
+
+## Maintainers
+
 * Jeff Yemin           jeff.yemin@mongodb.com
-* Trisha Gee           trisha.gee@mongodb.com
 * Ross Lawley          ross@mongodb.com
 
-### Contributors:
+## Contributors:
+* Trisha Gee           trisha.gee@gmail.com
 * Uladzmir Mihura      trnl.me@gmail.com
 * Justin Lee           justin.lee@mongodb.com
 * Craig Wilson         craig.wilson@mongodb.com
-* Scott Hernandez      scott@mongodb.com
 
-### Build status:
+Additional contributors can be found [here](https://github.com/mongodb/mongo-java-driver/graphs/contributors).
 
-[![Build Status](https://travis-ci.org/mongodb/mongo-java-driver.svg?branch=3.0.x)](https://travis-ci.org/mongodb/mongo-java-driver) | [![Build Status](https://jenkins.10gen.com/job/mongo-java-driver-3.0.x/badge/icon)](https://jenkins.10gen.com/job/mongo-java-driver-3.0.x/)
+## Supporters
+
+YourKit is supporting this open source project with its [YourKit Java Profiler](http://www.yourkit.com/java/profiler/index.jsp).
 
-### Java 8 Compatibility
-<img src="https://java.net/downloads/adoptopenjdk/compat.svg" alt="Compatibility Badge" style="max-width: 100px;" width="100px">
+JetBrains is supporting this open source project with [![Intellij IDEA](http://www.jetbrains.com/img/logos/logo_intellij_idea.png)]
+(http://www.jetbrains.com/idea/)
 
-We proudly develop this project with [![Intellij IDEA](http://www.jetbrains.com/img/logos/logo_intellij_idea.png)](http://www.jetbrains.com/idea/)