Skip to content

Commit

Permalink
Documentation updates for 2.1 (#237)
Browse files Browse the repository at this point in the history 
* Update distributables discription for Hamcrest 2.1
* Update changes for Hamcrest 2.1
* Add background and border to code samples.
  • Loading branch information
@tumbarumba
tumbarumba authored Dec 20, 2018
1 parent 7ffc219 commit 6519416
Show file tree
Hide file tree
Showing 3 changed files with 128 additions and 84 deletions.
45 changes: 20 additions & 25 deletions CHANGES.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down
5 changes: 5 additions & 0 deletions docs/css/hamcrest.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,8 @@ h1, h2 {
padding-left: 0px;
padding-right: 40px;
}
pre.highlight {
border: 1px solid #ccc;
background-color: #eee;
padding: 0.5em;
}
162 changes: 103 additions & 59 deletions docs/distributables.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
```

0 comments on commit 6519416

Please sign in to comment.