CONTRIBUTING.md changes + README.md changes

CONTRIBUTING.md

@@ -57,14 +57,13 @@ or [Eclipse](https://community.jboss.org/wiki/ContributingToHibernateUsingEclips
 
 Create a [topic branch](http://git-scm.com/book/en/Git-Branching-Branching-Workflows#Topic-Branches) 
 on which you will work.  The convention is to incorporate the JIRA issue key in the name of this branch,
-although this is more of a mnemonic strategy than a hard=and-fast rule - but doing so helps:
+although this is more of a mnemonic strategy than a hard-and-fast rule - but doing so helps:
 * remember what each branch is for 
 * isolate the work from other contributions you may be working on.  
 
+_If there is not already a JIRA issue covering the work you want to do, create one._
   
-This branch will be the base for 
+Assuming you will be working from the master branch and working
-.  If there is not already a JIRA issue
-covering the work you want to do, create one.  Assuming you will be working from the master branch and working
 on the JIRA HHH-123 : `git checkout -b HHH-123 master`
 
 
@@ -72,6 +71,7 @@ on the JIRA HHH-123 : `git checkout -b HHH-123 master`
 
 Do yo thing!
 
+
 ## Commit
 
 * Make commits of logical units.

README.md

@@ -9,18 +9,11 @@ JPA specification, which is the standardized Java specification for ORM.  See
 [![Build Status](http://ci.hibernate.org/job/hibernate-orm-master-h2-main/badge/icon)](http://ci.hibernate.org/job/hibernate-orm-master-h2-main/)
 
 
-Quickstart
+## Resources
-==========
-
-     git clone git://github.com/hibernate/hibernate-orm.git
-     cd hibernate-orm
-     ./gradlew clean build
 
 The build requires a Java 8 JDK as JAVA_HOME.
 
-
+You will need http://git-scm.com/[git] to obtain the http://github.com/hibernate/hibernate-orm/[source].
-Resources
-=========
 
 Hibernate uses [Gradle](http://gradle.org) as its build tool.  See the _Gradle Primer_ section below if you are new to
 Gradle.
@@ -28,21 +21,19 @@ Gradle.
 Contributors should read the [Contributing Guide](CONTRIBUTING.md)
 
 See the guides for setting up [IntelliJ](https://developer.jboss.org/wiki/ContributingToHibernateUsingIntelliJ) or
-[Eclipse](https://developer.jboss.org/wiki/ContributingToHibernateUsingEclipse) as your development environment.  [Building Hibernate ORM](https://community.jboss.org/wiki/BuildingHibernateORM4x) 
+[Eclipse](https://developer.jboss.org/wiki/ContributingToHibernateUsingEclipse) as your development environment.
-is somewhat outdated, but still has
+
+Check out the _Getting Started_ section in CONTRIBUTING.md for getting started working on Hibernate source.
 
 
-CI Builds
+## CI Builds
-=========
 
 Hibernate makes use of [Jenkins](http://jenkins-ci.org) for its CI needs.  The project is built continuous on each 
 push to the upstream repository.   Overall there are a few different jobs, all of which can be seen at 
 [http://ci.hibernate.org/view/ORM/](http://ci.hibernate.org/view/ORM/)
 
 
-
+## Gradle primer
-Gradle primer
-=============
 
 This section describes some of the basics developers and contributors new to Gradle might 
 need to know to get productive quickly.  The Gradle documentation is very well done; 2 in 
@@ -54,8 +45,7 @@ it follows a topical approach to describing all of the capabilities of Gradle.
 getting up to speed on certain aspects of Gradle.
 
 
-Using the Gradle Wrapper
+### Using the Gradle Wrapper
-------------------------
 
 For contributors who do not otherwise use Gradle and do not want to install it, Gradle offers a very cool
 features called the wrapper.  It lets you run Gradle builds without a previously installed Gradle distro in 
@@ -65,8 +55,14 @@ the command `gradlew` (or `gradlew.bat`) rather than `gradle` (or `gradle.bat`)
 Note that `gradlew` is only available in the project's root dir, so depending on your `pwd` you may need to adjust 
 the path to `gradlew` as well.
 
-Executing Tasks
+Examples use the `gradle` syntax, but just swap `gradlew` (properly relative) for `gradle` if you wish to use 
----------------
+the wrapper.
+
+_Note that another reason to use `gradlew` is that it uses the exact version of Gradle that the build is 
+defined to work with.
+
+
+### Executing Tasks
 
 Gradle uses the concept of build tasks (equivalent to Ant targets or Maven phases/goals). You can get a list of
 available tasks via 
@@ -80,8 +76,7 @@ either:
 1. `cd` into that module directory and execute the task
 2. name the "task path".  For example, in order to run the tests for the _hibernate-core_ module from the root directory you could say `gradle hibernate-core:test`
 
-Common Java related tasks
+### Common Java related tasks
--------------------------
 
 * _build_ - Assembles (jars) and tests this project
 * _buildDependents_ - Assembles and tests this project and all projects that depend on it.  So think of running this in hibernate-core, Gradle would assemble and test hibernate-core as well as hibernate-envers (because envers depends on core)
@@ -97,3 +92,57 @@ never uses this, but it can be useful for testing your build with other local Ma
 * _idea_ - Generates an IntelliJ/IDEA project (although the preferred approach is to use IntelliJ's Gradle import).
 * _clean_ - Cleans the build directory
 
+
+## Testing and databases
+
+Testing against a specific database can be achieved in 2 different ways:
+
+
+### Using the "Matrix Testing Plugin" for Gradle.
+
+Coming soon...
+
+
+### Using "profiles"
+
+The Hibernate build defines a number of database testing "profiles" in `databases.gradle`.  These
+profiles can be activated by name using the `db` build property which can be passed either as
+a JVM system prop (`-D`) or as a Gradle project property (`-P`).  Examples below use the Gradle
+project property approach.
+
+[source]
+----
+gradle clean build -Pdb=pgsql
+----
+
+To run a test from your IDE, you need to ensure the property expansions happen.
+Use the following command:
+
+[source]
+----
+gradle clean compile -Pdb=pgsql
+----
+
+[NOTE]
+====
+To run the tests from your IDEs for Oracle, DB2 and other non-OSS JDBC drivers, it is a bit different.
+You also need to edit `build.gradle` and change the following (e.g for Oracle DB).
+
+[source]
+----
+// from
+if (db.equalsIgnoreCase("oracle")) {
+  dependencies {
+    testRuntime( libraries.oracle )
+  }
+}
+
+//to
+dependencies {
+  testRuntime( libraries.oracle )
+}
+----
+
+Also remember to add the Oracle driver to your local Maven repository.
+Oracle drivers are not on Maven central.
+====