diff --git a/CHANGES.md b/CHANGES.md index f56ea579..8539b8fd 100644 --- 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-.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 index 2a5d8317..c456ed90 100644 --- 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; +} \ No newline at end of file diff --git a/docs/distributables.md b/docs/distributables.md index f8db64aa..dde75ac7 100644 --- a/docs/distributables.md +++ b/docs/distributables.md @@ -10,9 +10,16 @@ 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} @@ -20,88 +27,125 @@ functionality contained in each of them. * 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 `` section in your `pom.xml`: ```xml org.hamcrest - hamcrest-library - 1.3 + hamcrest + 2.1 test ``` -### 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 + + + org.hamcrest + hamcrest + 2.1 + test + + + org.hamcrest + hamcrest-library + 2.1 + test + + + junit + junit + 4.12 + test + + +```