From c4a5fd952571ed7673878676b6180c8f7ccbaade Mon Sep 17 00:00:00 2001 From: Ryan McNally Date: Thu, 13 Jul 2023 11:31:41 +0100 Subject: [PATCH] bom (#460) * Added bom * no need for this any more! * Automated readme header --- README.md | 1 + assert/assert-junit4/README.md | 3 +- assert/assert-junit5/README.md | 3 +- bom/README.md | 69 +++++++++ bom/pom.xml | 132 ++++++++++++++++++ builder/README.md | 3 +- doc/pom.xml | 25 ++-- doc/src/main/markdown/quickstart.md | 37 +++-- .../test/flow/doc/DependencyTest.java | 20 ++- .../mastercard/test/flow/doc/SnippetTest.java | 21 +-- message/message-core/README.md | 4 +- message/message-http/README.md | 4 +- message/message-json/README.md | 3 +- message/message-sql/README.md | 3 +- message/message-text/README.md | 3 +- message/message-web/README.md | 3 +- message/message-xml/README.md | 3 +- model/README.md | 3 +- pom.xml | 1 + validation/validation-junit4/README.md | 3 +- validation/validation-junit5/README.md | 3 +- 21 files changed, 284 insertions(+), 63 deletions(-) create mode 100644 bom/README.md create mode 100644 bom/pom.xml diff --git a/README.md b/README.md index a057533608..4c6c05e69d 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ Testing framework * [validation](validation) Checking model consistency * [assert](assert) Comparing models against systems * [report](report) Visualising assertion results + * [bom](bom) Bill of materials * [aggregator](aggregator) Aggregates build artifacts * [example](example) Service constellation to exercise the flow framework * [doc](doc) Documentation resources diff --git a/assert/assert-junit4/README.md b/assert/assert-junit4/README.md index 89d5d677c3..b9fa801be3 100644 --- a/assert/assert-junit4/README.md +++ b/assert/assert-junit4/README.md @@ -18,12 +18,13 @@ It provides the `Flocessor` the `FlowRule` classes, which should be combined in ## Usage +After [importing the `bom`](../../bom): + ```xml com.mastercard.test.flow assert-junit4 - ${flow.version} test ``` diff --git a/assert/assert-junit5/README.md b/assert/assert-junit5/README.md index 56639684d5..52938220ec 100644 --- a/assert/assert-junit5/README.md +++ b/assert/assert-junit5/README.md @@ -18,12 +18,13 @@ It provides the `Flocessor` class, which should be used as a generator for a [dy ## Usage +After [importing the `bom`](../../bom): + ```xml com.mastercard.test.flow assert-junit5 - ${flow.version} test ``` diff --git a/bom/README.md b/bom/README.md new file mode 100644 index 0000000000..003405d2f1 --- /dev/null +++ b/bom/README.md @@ -0,0 +1,69 @@ + + + +# bom + +Bill of materials + + + + * [../flow](https://github.com/Mastercard/flow) Testing framework + + + +## Overview + +This pom-only project offers a mechanism to coordinate the versions of the other flow artifacts that you consume. + +## Usage + +Import the bom into the `/project/dependencyManagement` section of your pom file: + +```xml + + ... + + + + + com.mastercard.test.flow + bom + x.y.x + pom + import + + + + ... + +``` +The latest release version is [![Maven Central](https://img.shields.io/maven-central/v/com.mastercard.test.flow/parent)](https://search.maven.org/search?q=com.mastercard.test.flow). + +The versions of other flow artifacts in your `/project/dependencies` section will then automatically match that of the bom: + +```xml + + ... + + + + com.mastercard.test.flow + builder + + + + com.mastercard.test.flow + group + + + + com.mastercard.test.flow + message-json + + + ... + +``` + +At some point you'll find yourself having to track down the source of a dependency version, a task that is complicated by the use of bom imports. +Running `mvn help:effective-pom -Dverbose=true` will be instructive in such cases. diff --git a/bom/pom.xml b/bom/pom.xml new file mode 100644 index 0000000000..4089905f9a --- /dev/null +++ b/bom/pom.xml @@ -0,0 +1,132 @@ + + + 4.0.0 + + com.mastercard.test.flow + parent + 0.0.16-SNAPSHOT + + bom + pom + Bill of materials + + + + + + ${project.groupId} + api + ${project.version} + + + + com.mastercard.test.flow + builder + ${project.version} + + + + com.mastercard.test.flow + message-core + ${project.version} + + + + com.mastercard.test.flow + message-text + ${project.version} + + + + ${project.groupId} + message-json + ${project.version} + + + + ${project.groupId} + message-http + ${project.version} + + + + ${project.groupId} + message-sql + ${project.version} + + + + ${project.groupId} + message-web + ${project.version} + + + + ${project.groupId} + message-xml + ${project.version} + + + + com.mastercard.test.flow + model + ${project.version} + + + + ${project.groupId} + validation-core + ${project.version} + + + + ${project.groupId} + validation-junit4 + ${project.version} + + + + com.mastercard.test.flow + validation-junit5 + ${project.version} + + + + com.mastercard.test.flow + coppice + ${project.version} + + + + ${project.groupId} + report-core + ${project.version} + + + + ${project.groupId} + assert-filter + ${project.version} + + + + ${project.groupId} + assert-core + ${project.version} + + + + ${project.groupId} + assert-junit4 + ${project.version} + + + + com.mastercard.test.flow + assert-junit5 + ${project.version} + + + + + diff --git a/builder/README.md b/builder/README.md index f1d539cb7e..eba341a806 100644 --- a/builder/README.md +++ b/builder/README.md @@ -38,12 +38,13 @@ and in the [example system model project](../example/app-model). ## Usage +After [importing the `bom`](../bom): + ```xml com.mastercard.test.flow builder - ${flow.version} ``` diff --git a/doc/pom.xml b/doc/pom.xml index 1d14ea7581..bfb5a414f0 100644 --- a/doc/pom.xml +++ b/doc/pom.xml @@ -10,6 +10,19 @@ jar Documentation resources + + + + + com.mastercard.test.flow + bom + ${project.version} + pom + import + + + + ${project.groupId} @@ -22,7 +35,6 @@ com.mastercard.test.flow builder - ${project.version} @@ -31,20 +43,17 @@ com.mastercard.test.flow message-text - ${project.version} ${project.groupId} message-json - ${project.version} ${project.groupId} message-http - ${project.version} @@ -52,38 +61,32 @@ com.mastercard.test.flow model - ${project.version} ${project.groupId} validation-core - ${project.version} ${project.groupId} validation-junit4 - ${project.version} ${project.groupId} report-core - ${project.version} ${project.groupId} assert-core - ${project.version} ${project.groupId} assert-junit4 - ${project.version} @@ -91,7 +94,6 @@ com.mastercard.test.flow validation-junit5 - ${project.version} test @@ -101,7 +103,6 @@ com.mastercard.test.flow assert-junit5 - ${project.version} test diff --git a/doc/src/main/markdown/quickstart.md b/doc/src/main/markdown/quickstart.md index d31f760a7b..22bf8f6f1e 100644 --- a/doc/src/main/markdown/quickstart.md +++ b/doc/src/main/markdown/quickstart.md @@ -7,13 +7,27 @@ This guide will take you from an empty project to a full, if basic, flow-tested ## Dependency management This library is published as a set of tightly-scoped and loosely-coupled jars. -Each of the artifacts you consume should have the same version number, so it's best to define the library version in a property and reuse that in all dependency declarations: +Each of the artifacts you consume should have the same version number, which can be conveniently achieved by importing the bill of materials pom: ```xml - - x.y.z - + + ... + + + + + com.mastercard.test.flow + bom + x.y.x + pom + import + + + + ... + ``` + The latest release version is [![Maven Central](https://img.shields.io/maven-central/v/com.mastercard.test.flow/parent)](https://search.maven.org/search?q=com.mastercard.test.flow). Bear in mind that the artifacts provided by this project are intended for usage in testing only. @@ -58,10 +72,9 @@ Add a dependency: com.mastercard.test.flow builder - ${flow.version} ``` -[Snippet context](../../../pom.xml#L21-L26,21-26) +[Snippet context](../../../pom.xml#L34-L38,34-38) @@ -106,10 +119,9 @@ For our purposes the [`Text` message type][txt.Text] is appropriate, so we add a com.mastercard.test.flow message-text - ${flow.version} ``` -[Snippet context](../../../pom.xml#L30-L35,30-35) +[Snippet context](../../../pom.xml#L42-L46,42-46) @@ -193,10 +205,9 @@ To package flows together we'll need: com.mastercard.test.flow model - ${flow.version} ``` -[Snippet context](../../../pom.xml#L51-L56,51-56) +[Snippet context](../../../pom.xml#L60-L64,60-64) @@ -240,11 +251,10 @@ To use these, add a dependency: com.mastercard.test.flow validation-junit5 - ${flow.version} test ``` -[Snippet context](../../../pom.xml#L90-L96,90-96) +[Snippet context](../../../pom.xml#L93-L98,93-98) @@ -292,11 +302,10 @@ Add a dependency: com.mastercard.test.flow assert-junit5 - ${flow.version} test ``` -[Snippet context](../../../pom.xml#L100-L106,100-106) +[Snippet context](../../../pom.xml#L102-L107,102-107) diff --git a/doc/src/test/java/com/mastercard/test/flow/doc/DependencyTest.java b/doc/src/test/java/com/mastercard/test/flow/doc/DependencyTest.java index 2c4c704664..009b1a0fc7 100644 --- a/doc/src/test/java/com/mastercard/test/flow/doc/DependencyTest.java +++ b/doc/src/test/java/com/mastercard/test/flow/doc/DependencyTest.java @@ -2,6 +2,7 @@ import static java.nio.charset.StandardCharsets.UTF_8; import static java.util.stream.Collectors.joining; +import static java.util.stream.Collectors.toSet; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertTrue; @@ -17,6 +18,7 @@ import java.util.regex.Pattern; import java.util.stream.Stream; +import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.DynamicNode; import org.junit.jupiter.api.TestFactory; @@ -28,11 +30,21 @@ @SuppressWarnings("static-method") class DependencyTest { - private static Pattern DEP = Pattern.compile( "(.*)", Pattern.DOTALL ); + private static Pattern DEP = Pattern.compile( "(.*?)", Pattern.DOTALL ); private static Pattern GRP = Pattern.compile( "(.*)" ); private static Pattern RTF = Pattern.compile( "(.*)" ); private static Pattern VRS = Pattern.compile( "(.*)" ); + /** + * These files contain dependency declarations that aren't so trivially + * validated, so we'll skip over them here and trust to manual review. + */ + private static final Set EXCLUDED = Stream.of( + "../bom/README.md", + "../doc/src/main/markdown/quickstart.md" ) + .map( Paths::get ) + .collect( toSet() ); + /** * Checks that all of the suggested dependency declarations in the readmes * accurately target an artifact from this project @@ -54,6 +66,7 @@ Stream markdown() { return Stream.concat( Util.markdownFiles() + .filter( p -> !EXCLUDED.contains( p ) ) .map( path -> dynamicTest( path.toString(), () -> { String content = new String( QuietFiles.readAllBytes( path ), UTF_8 ); Matcher depM = DEP.matcher( content ); @@ -64,10 +77,9 @@ Stream markdown() { Matcher rtfM = RTF.matcher( depM.group( 1 ) ); assertTrue( rtfM.find(), "artifactId found in " + depM.group( 0 ) ); + // our documentation assumes a bom import, so we shouldn't have a version Matcher vrsM = VRS.matcher( depM.group( 1 ) ); - assertTrue( vrsM.find(), "version found in " + depM.group( 0 ) ); - assertEquals( "${flow.version}", vrsM.group( 1 ), - "Version element in\n" + depM.group( 0 ) ); + Assertions.assertFalse( vrsM.find(), "version found in " + depM.group( 0 ) ); String dep = grpM.group( 1 ) + ":" + rtfM.group( 1 ); used.add( dep ); diff --git a/doc/src/test/java/com/mastercard/test/flow/doc/SnippetTest.java b/doc/src/test/java/com/mastercard/test/flow/doc/SnippetTest.java index 8b747fc910..5a3b71da88 100644 --- a/doc/src/test/java/com/mastercard/test/flow/doc/SnippetTest.java +++ b/doc/src/test/java/com/mastercard/test/flow/doc/SnippetTest.java @@ -9,7 +9,6 @@ import java.io.UncheckedIOException; import java.nio.file.Files; import java.nio.file.Path; -import java.nio.file.Paths; import java.util.ArrayList; import java.util.Arrays; import java.util.Collections; @@ -18,7 +17,6 @@ import java.util.List; import java.util.Map; import java.util.Map.Entry; -import java.util.function.UnaryOperator; import java.util.regex.Matcher; import java.util.regex.Pattern; import java.util.stream.Stream; @@ -70,22 +68,6 @@ class SnippetTest { private static final String MD_END = ""; private static final Pattern MD_SNIPPET_DESCRIPTOR = Pattern.compile( "" ); - private static final Map> MUTATIONS; - static { - Map> m = new HashMap<>(); - // Ideally we'd have a - // ${project.version} - // in the pom so that the dependencies are consistent with how they'd be - // declared in an actual client project. - // https://issues.apache.org/jira/browse/MRELEASE-799 scuppers that, so we're - // reduced to mutating the snippets as they are extracted. The markdown will - // look ok, but it'll be inconsistent with the actual pom file. - // I'm unhappy about this. - m.put( Paths.get( "pom.xml" ).getFileName(), - s -> s.replace( "${project.version}", "${flow.version}" ) ); - MUTATIONS = Collections.unmodifiableMap( m ); - } - private static final Map SOURCE_DELIMITERS; static { Map m = new HashMap<>(); @@ -157,8 +139,7 @@ private Snippet extract( Path file, String name ) { while( lines.hasNext() ) { lineNumber++; - String line = MUTATIONS.getOrDefault( file.getFileName(), s -> s ) - .apply( lines.next() ); + String line = lines.next(); Delimiter sd = delimiter( file ); Matcher start = sd.start.matcher( line.trim() ); diff --git a/message/message-core/README.md b/message/message-core/README.md index 3dc093cb6c..89166f342e 100644 --- a/message/message-core/README.md +++ b/message/message-core/README.md @@ -15,11 +15,13 @@ Message implementation utilities You'll only need to consume this artifact directly if you're implementing your own `Message` type. + +After [importing the `bom`](../../bom): + ```xml com.mastercard.test.flow message-core - ${flow.version} ``` \ No newline at end of file diff --git a/message/message-http/README.md b/message/message-http/README.md index aee5035921..7da3ea2d55 100644 --- a/message/message-http/README.md +++ b/message/message-http/README.md @@ -13,12 +13,14 @@ HypterText Transfer Protocol messages ## Usage + +After [importing the `bom`](../../bom): + ```xml com.mastercard.test.flow message-http - ${flow.version} ``` diff --git a/message/message-json/README.md b/message/message-json/README.md index e5dede767e..671c76e497 100644 --- a/message/message-json/README.md +++ b/message/message-json/README.md @@ -13,12 +13,13 @@ JavaScript Object Notation Messages ## Usage +After [importing the `bom`](../../bom): + ```xml com.mastercard.test.flow message-json - ${flow.version} ``` diff --git a/message/message-sql/README.md b/message/message-sql/README.md index 344341dd30..a730253d3f 100644 --- a/message/message-sql/README.md +++ b/message/message-sql/README.md @@ -13,12 +13,13 @@ Structured Query Language messages ## Usage +After [importing the `bom`](../../bom): + ```xml com.mastercard.test.flow message-sql - ${flow.version} ``` diff --git a/message/message-text/README.md b/message/message-text/README.md index 7aa1d90c02..e40199d6ee 100644 --- a/message/message-text/README.md +++ b/message/message-text/README.md @@ -13,12 +13,13 @@ Freeform text Message ## Usage +After [importing the `bom`](../../bom): + ```xml com.mastercard.test.flow message-text - ${flow.version} ``` diff --git a/message/message-web/README.md b/message/message-web/README.md index 2161c9514d..3ce88fb4d8 100644 --- a/message/message-web/README.md +++ b/message/message-web/README.md @@ -13,12 +13,13 @@ Browser interaction messages ## Usage +After [importing the `bom`](../../bom): + ```xml com.mastercard.test.flow message-web - ${flow.version} ``` diff --git a/message/message-xml/README.md b/message/message-xml/README.md index 5c909c3c9f..a04e145ec6 100644 --- a/message/message-xml/README.md +++ b/message/message-xml/README.md @@ -13,12 +13,13 @@ Extensible Markup Language Messages ## Usage +After [importing the `bom`](../../bom): + ```xml com.mastercard.test.flow message-xml - ${flow.version} ``` diff --git a/model/README.md b/model/README.md index 227876c54c..81c5ca5558 100644 --- a/model/README.md +++ b/model/README.md @@ -37,12 +37,13 @@ Thus when we're iterating on changing the `foo` behaviour we can supply the `foo ## Usage +After [importing the `bom`](../bom): + ```xml com.mastercard.test.flow model - ${flow.version} ``` diff --git a/pom.xml b/pom.xml index 26c76fd339..5deeae305a 100644 --- a/pom.xml +++ b/pom.xml @@ -32,6 +32,7 @@ validation assert report + bom aggregator example doc diff --git a/validation/validation-junit4/README.md b/validation/validation-junit4/README.md index 880b5e0058..15d1a88903 100644 --- a/validation/validation-junit4/README.md +++ b/validation/validation-junit4/README.md @@ -13,13 +13,14 @@ Junit4 validation components ## Usage +After [importing the `bom`](../../bom): + ```xml com.mastercard.test.flow validation-junit4 - ${flow.version} ``` diff --git a/validation/validation-junit5/README.md b/validation/validation-junit5/README.md index 527ca5c586..71ec4e5302 100644 --- a/validation/validation-junit5/README.md +++ b/validation/validation-junit5/README.md @@ -13,13 +13,14 @@ Junit5 validation components ## Usage +After [importing the `bom`](../../bom): + ```xml com.mastercard.test.flow validation-junit5 - ${flow.version} ```