From bc36608d67b1167e6937a848ee8f239bc7c5e946 Mon Sep 17 00:00:00 2001
From: Rune Flobakk <flobakk@gmail.com>
Date: Sun, 4 Feb 2024 21:16:19 +0100
Subject: [PATCH] Add getting started section to readme

---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/README.md b/README.md
index d3f077f..c97a68e 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,6 @@
+![Maven Central Version](https://img.shields.io/maven-central/v/com.github.runeflobakk/record-matcher-maven-plugin)
+
+
 # Record Matcher Generator
 
 A library and plugin for Maven to generate source code for [Hamcrest Matchers](https://hamcrest.org/JavaHamcrest/) for [Java records](https://openjdk.org/jeps/395). The generated matchers provide an API to incrementally constrain how specific you want to express what your expectations are in test. reflecting the names of both the record itself as well as its components (i.e. fields)
@@ -5,6 +8,71 @@ A library and plugin for Maven to generate source code for [Hamcrest Matchers](h
 This project is currently in its infancy, but should still be usable. You are most welcome to play around with it, and I appreciate any feedback you may have!
 
 
+## Getting started
+
+Likely, you want to use this via the Maven plugin, and this is how you would set that up in your `pom.xml`:
+
+
+```xml
+<build>
+	<plugins>
+		<plugin>
+			<groupId>com.github.runeflobakk</groupId>
+				<artifactId>record-matcher-maven-plugin</artifactId>
+				<version>0.1.0</version> <!-- replace with any newer version -->
+				<configuration>
+					<includes>
+						<!--
+						For now, the records for which you want matchers generated needs to be enumerated.
+						An automated discovery facility is planned for later.
+						-->
+						<include>your.domain.SomeRecord</include>
+						<include>your.domain.sub.SomeOtherRecord</include>
+					</includes>
+				</configuration>
+				<executions>
+					<execution>
+						<goals>
+							<goal>generate</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+    ...
+```
+Or separate the execution binding and configuration by putting the configuration into `pluginManagement`, if you prefer.
+
+The configuration above will generate the source code for `SomeRecordMatcher` and `SomeOtherRecordMatcher` and put them in `target/generated-test-sources/record-matchers` in the corresponding packages as each record they match on.
+
+The plugin will itself include the folder where it generates code as a test source root for the compiler. If your IDE is able to resolve source folders automatically based on any `build-helper-maven-plugin` configuration, you may also want to include this:
+
+```xml
+<plugin>
+	<groupId>org.codehaus.mojo</groupId>
+	<artifactId>build-helper-maven-plugin</artifactId>
+	<version>3.5.0</version>
+	<executions>
+		<execution>
+			<id>include-record-matchers</id>
+			<goals>
+				<goal>add-test-source</goal>
+			</goals>
+			<configuration>
+				<sources>
+					<source>target/generated-test-sources/record-matchers</source>
+				</sources>
+			</configuration>
+		</execution>
+	</executions>
+</plugin>
+```
+
+Eclipse detects this, and to my knowledge IntelliJ should also support this. Alternatively, you will need to manually add `target/generated-test-sources/record-matchers` as a test source folder for your project in your IDE.
+
+After running a build, or `mvn generate-test-sources`, you should be able to see the generated Matcher classes in your IDE. The example given above would make a `SomeRecordMatcher` and `SomeOtherRecordMatcher` available (substitute with your own record(s)), and their static factory methods `SomeRecordMatcher.aSomeRecord()` and `SomeOtherRecordMatcher.aSomeOtherRecord()` which should provide their APIs via method chaining; you get autocompletion by typing `.` after the static factory method.
+
+
+
 ## Use cases
 
 ### Tests