Documentation updates for 2.1 (hamcrest#237)

tumbarumba · web-flow · commit 6519416cc467 · 2018-12-21T05:57:03.000+11:00
* Update distributables discription for Hamcrest 2.1
* Update changes for Hamcrest 2.1
* Add background and border to code samples.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,49 +1,44 @@
 # Hamcrest Changes
 
-## Version 2.1-rc2 (27th November 2018)
+## Version 2.1 (Unreleased)
 
-* Publish pom-only artifacts for hamcrest-core and hamcrest-library.
-
-## Version 2.1-rc1 (25th November 2018)
-
-### Overview for 2.1-rc1
+### Overview for 2.1
 
 After a long hiatus without releases, this version simplifies the packaging of
 Hamcrest into a single jar: `hamcrest-<version>.jar`. Other big changes include
-Java 9 module compatibility, along with numerous other improvements and bug
-fixes.
+Java 9 module compatibility, migrating the code repository from Google Code to
+GitHub, along with numerous other new features, improvements and bug fixes.
 
-### Breaking Changes for 2.1-rc1
+### Breaking Changes for 2.1
 
-Although the class API has not changed since Hamcrest 1.3, the way that the
-project is packaged has changed. Refer to the [Hamcrest Distributables](http://hamcrest.org/JavaHamcrest/distributables.html)
-documentation for more information. 
+* The way that the project is packaged has changed. This may cause problems with
+correctly upgrading transitive dependencies. Refer to the
+[Hamcrest Distributables](http://hamcrest.org/JavaHamcrest/distributables.html)
+documentation for more information, and in particular,
+[Upgrading from Hamcrest 1.x](http://hamcrest.org/JavaHamcrest/distributables.html#upgrading-from-hamcrest-1.x)
+* `org.hamcrest.Factory` has been removed. This was only used in old implementations
+of the hamcrest build toolchain, and can safely be deleted from client code without
+any effect.
 
-### Changes for 2.1-rc1
+### Changes for 2.1
 
-* Publish a single jar `hamcrest-2.1.jar`
 * Documentation updates
+* Several JavaDoc improvements and corrections
+* Fix JavaDoc examples
+* Upgraded to Java 7
+* Build with Gradle
+* Publish a single jar `hamcrest-2.1.jar`
+* Publish pom-only artifacts for `hamcrest-core` and `hamcrest-library`.
 * Add implementation for CharSequence length matcher
 * Fix for TypeSafeDiagnosingMatcher can't detect generic types for subclass
-* Renamed IsCollectionContaining to IsIterableContaining
 * Make Hamcrest an OSGI bundle
 * Add StringRegularExpression matcher
 * Fix StringContainsInOrder to detect if a repeated pattern is missing 
 * Add ArrayAsIterableMatcher
 * Fix description for IsEqualIgnoringCase
-* Fix JavaDoc examples
-
-## Version 2.0.0.0 (18th January 2015)
-
-This version was the first release after migrating from the old Google Code hosting to GitHub.
-
-* Upgraded to Java 7
-* Build with Gradle
-* Publish a single jar java-hamcrest-2.0.0.0.jar
 * Removed deprecated methods from previous release
 * Improve mismatch description of hasItem/hasItems
 * General improvements to mismatch descriptions
-* Several JavaDoc improvements and corrections
 * Deprecated several matcher factory methods of the for "isXyz"
 * Fix [GH issue #75](https://github.com/hamcrest/JavaHamcrest/issues/75) - address doclint errors reported in JDK 1.8
 * Fix [GH issue #69](https://github.com/hamcrest/JavaHamcrest/issues/69) - Iterable contains in order is null-safe
diff --git a/docs/css/hamcrest.css b/docs/css/hamcrest.css
@@ -37,3 +37,8 @@ h1, h2 {
   padding-left: 0px;
   padding-right: 40px;
 }
+pre.highlight {
+  border: 1px solid #ccc;
+  background-color: #eee;
+  padding: 0.5em;
+}
diff --git a/docs/distributables.md b/docs/distributables.md
@@ -10,98 +10,142 @@ layout: default
 ## Introduction
 {:.no_toc}
 
-Hamcrest consists of different jars matching the different needs of
-applications. This document describes these distributables and the
-functionality contained in each of them.
+This document describes the current and previous versions of the various Hamcrest
+distributables, and the functionality contained in each of them.
+
+The latest version of Hamcrest consists of a single jar file which contains base
+classes and a library of useful matcher implementations. This is different from
+older versions.
+
+Older versions of Hamcrest consisted of a number of different jars matching the
+different needs of applications. The change in the jar packaging requires care
+when upgrading.
 
 ## Table of Contents
 {:.no_toc}
 
 * TOC
 {:toc}
 
-## The Java Hamcrest Jars
-
-### `hamcrest-core.jar`
-
-This is the core API to be used by third-party framework providers.
-This includes a foundation set of matcher implementations for common
-operations. This API is stable and will rarely change. You will
-need this library as a minimum.
-
-### `hamcrest-library.jar`
-
-The library of Matcher implementations which are based on the core 
-functionality in hamcrest-core.jar.
-
-### `hamcrest-integration.jar`
-
-Provides integration between Hamcrest and other testing tools, such as jMock
-and EasyMock. Uses hamcrest-core.jar and hamcrest-library.jar.
-
-### `hamcrest-generator.jar`
-
-A tool to allow many Matcher implementations to be combined into
-a single class with static methods returning the different matchers 
-so users don't have to remember many classes/packages to import. 
-Generates code. This library is only used internally at compile time.
-It is not necessary for the use of any of the other hamcrest libraries 
-at runtime.
-
-### `hamcrest-all.jar`
-
-One jar containing all classes of all the other jars.
-
-
-## Adding Hamcrest to your Project
+## The Hamcrest Jar
 
-The dependencies of the jars (`hamcrest-integration` uses `hamcrest-library`
-which uses `hamcrest-core`) is represented by the Maven dependency mechanism.
-There is no `hamcrest-all` library in the Maven repo prior to version 1.3. Just
-use hamcrest-integration which references all the other hamcrest libraries.
- 
+All the base classes and standard matcher implementations are contained in a
+single jar file called `hamcrest-2.1.jar`.
 
-### Gradle
+### Using Hamcrest in a Gradle Project
 
-Add `"org.hamcrest:hamcrest-library:1.3"` to the dependencies section of your
+Add `"org.hamcrest:hamcrest:2.1"` to the dependencies section of your
 `build.gradle`, for example:
 
 ```gradle
 apply plugin: 'java'
 
 dependencies {
-    testImplementation 'org.hamcrest:hamcrest-library:1.3'
+    testImplementation 'org.hamcrest:hamcrest:2.1'
 }
 ```
 
 Note: older versions of Gradle use the `testCompile` configuration
 instead of the `testImplementation` configuration.
 
-### Maven
+### Using Hamcrest in a Maven Project
 
-Add the following dependency declaration to your `pom.xml`:
+Add the following to the `<dependencies>` section in your `pom.xml`:
 
 ```xml
 <dependency>
     <groupId>org.hamcrest</groupId>
-    <artifactId>hamcrest-library</artifactId>
-    <version>1.3</version>
+    <artifactId>hamcrest</artifactId>
+    <version>2.1</version>
     <scope>test</scope>
 </dependency>
 ```
 
-### Download
+### Download the Hamcrest Jar
 
-You can download the jars directly from Maven Central. At a minimum, you will
-need `hamcrest-core.jar`, though most people will also use
-`hamcrest-library.jar` too. If you want to integrate Hamcrest Matchers with
-other test tools, such as jMock or EasyMock, download `hamcrest-integration.jar`, too.
-
-You can find the jars by searching Maven Central for groupId `org.hamcrest`
+You can download the jars directly from Maven Central. You can find the jars by searching Maven Central for groupId `org.hamcrest`
 using the following link:
 
 > [https://search.maven.org/search?q=g:org.hamcrest](https://search.maven.org/search?q=g:org.hamcrest) 
 
-Maven central has some extra artifacts called `java-hamcrest` and `hamcrest-java`,
-with a version of `2.0.0.0`. Please do not use these, as they are an aborted effort
-at repackaging the different jars.
+## Previous Versions of Hamcrest
+
+Prior to version 2.x, Hamcrest was distributed through multiple jars, described
+below. 
+
+* **`hamcrest-core.jar`**: This was the core API to be used by third-party framework
+providers. This includes a foundation set of matcher implementations for common
+operations. This library was used as a dependency for many third-party libraries, 
+including JUnit 4.x. From Hamcrest version 2.x, all the classes in
+`hamcrest-core.jar` were moved into `hamcrest.jar`.
+* **`hamcrest-library.jar`**: The library of Matcher implementations which are based
+on the core functionality in hamcrest-core.jar. From Hamcrest version 2.x, all the
+classes in `hamcrest-core.jar` were moved into `hamcrest.jar`.
+* **`hamcrest-integration.jar`**: Provides integration between Hamcrest and other
+testing tools, such as jMock and EasyMock. It depends upon `hamcrest-core.jar` and
+`hamcrest-library.jar`. There are no new releases of this library since version 1.3.
+* **`hamcrest-generator.jar`**: A tool to allow many Matcher implementations to be
+combined into a single class with static methods returning the different matchers 
+so users don't have to remember many classes/packages to import. Generates code.
+This library is only used internally at compile time. It is not necessary for the
+use of any of the other hamcrest libraries at runtime. There are no new releases of
+this library since version 1.3.
+* **`hamcrest-all.jar`**: One jar containing all classes of all the other jars.
+There are no new releases of this library since version 1.3. Please use the single
+`hamcrest.jar` instead.
+
+### Upgrading from Hamcrest 1.x
+
+Care must be taken when upgrading from Hamcrest 1.3 or earlier. Due to the change in
+packaging, the version conflict resolution that happens in dependency management
+tools won't happen automatically. A common example is projects that depend upon
+JUnit 4. JUnit 4 declares a transitive dependency upon `hamcrest-core-1.3.jar`.
+Because `hamcrest-core` is not the same artifact as `hamcrest`, it will not be
+upgraded.
+
+To address this issue, Hamcrest 2.1 and later also publish artifacts for
+`hamcrest-core` and `hamcrest-library`. Although these jars contain no classes,
+they trigger the version conflict upgrade in the dependency manager, and correctly
+declare transitive dependencies upon the new `hamcrest` packaging. Users can
+directly declare a dependency upon these shim jars to force the upgrade.
+
+#### Gradle Upgrade Example
+
+```gradle
+apply plugin: 'java'
+
+dependencies {
+    testImplementation 'org.hamcrest:hamcrest:2.1'
+    testImplementation 'org.hamcrest:hamcrest-library:2.1'
+    testImplementation 'junit:junit:4.12'
+}
+```
+
+#### Maven Upgrade Example
+
+**Warning**:
+Maven users should declare a dependency upon `hamcrest-library` **before** other
+dependencies, otherwise the older version will take precedence.  
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>org.hamcrest</groupId>
+        <artifactId>hamcrest</artifactId>
+        <version>2.1</version>
+        <scope>test</scope>
+    </dependency>
+    <dependency>
+        <groupId>org.hamcrest</groupId>
+        <artifactId>hamcrest-library</artifactId>
+        <version>2.1</version>
+        <scope>test</scope>
+    </dependency>
+    <dependency>
+        <groupId>junit</groupId>
+        <artifactId>junit</artifactId>
+        <version>4.12</version>
+        <scope>test</scope>
+    </dependency>
+</dependencies>
+```

Original file line number	Diff line number	Diff line change
`@@ -37,3 +37,8 @@ h1, h2 {`
`37`	`37`	`padding-left: 0px;`
`38`	`38`	`padding-right: 40px;`
`39`	`39`	`}`
	`40`	`+pre.highlight {`
	`41`	`+ border: 1px solid #ccc;`
	`42`	`+ background-color: #eee;`
	`43`	`+ padding: 0.5em;`
	`44`	`+}`