Follow Best Pratices for Java Libraries

[mjacoby]

Please,

• review Google Best Practices for Java Libraries and
• evaluate where it should be applied and considered into our code

[mjacoby]

My take on how the Best Practices affect aas4j

JLBP #	Name	Effort	Notes
1	Minimize dependencies	low/medium	done #137
2	Minimize API surface	medium/high	to be done - V1.0.0 - For each class/method decide if public/final
3	Use Semantic Versioning	none/low	done - optimal: find tool to ensure compliance to semantic versioning
4	Avoid dependencies on unstable libraries and features	none	partially done, automation open
5	Do not include a class in more than one classpath entry	none	N/A
6	Rename artifacts and packages together	none	when changing maven coordinates change namespace too (which is what we are going to do anyways)
7	Make breaking transitions easy	none	not done, relevant after V1.0.0 - optional: guidelines how to do breaking changes (e.g. by using @deprecated)
8	Advance widely used functionality to a stable version	none	in progress
9	Support the minimum Java version of your consumers	low/none	done - Currently using Java 11, maybe Java 13 in later versions
10	Maintain API stability as long as needed for consumers	none/low	TBD for V1.1.0 - concept how to maintain old versions of meta model in the future
11	Keep dependencies up to date	low/medium	done - use Dependabot, plan for regular releases (as dependencies update rather often)
12	Make level of support and API stability clear	low	done in README - incubating, stable, archived
13	Remove references to deprecated features in dependencies at the first opportunity	?	to be done for V1.1.0 - should be able to automatically scan for this, probably compiler gives a warning
14	Specify a single, overridable version of each dependency	low	done #137
15	Publish a BOM for multi-module projects	?	BOM or SBOM? - TBD, but relevant V1.0.0
16	Ensure upper version alignment of dependencies for consumers	low	TO DO after V1.1.0
17	Coordinate rollout of breaking changes	none	TBD - after V1.1.0
18	Only shade dependencies as a last resort	none	N/A
19	Place each package in only one module	none	done
20	Give each JAR file a module name	low	TBD - https://jlbp.dev/JLBP-20
21	Upload artifacts to Maven Central		done
22	Declare all direct dependencies	low/medium	done #137

[kenwenzel]

Some notes from my side:

JLBP #	Name	Effort	Notes
9	Support the minimum Java version of your consumers	low/none	Java 11 should stay the minimum nowadays
11	Keep dependencies up to date	low/medium	use https://www.mojohaus.org/versions-maven-plugin/
14	Specify a single, overridable version of each dependency	low	use Maven property like jackson.version with dependenyManagement and https://www.mojohaus.org/flatten-maven-plugin/
15	Publish a BOM for multi-module projects	?	provide a POM with a dependenyManagement section that declares the current vesion of all modules - see also https://rdf4j.org/documentation/programming/setup/#the-bom-bill-of-materials and https://github.com/eclipse/rdf4j/blob/main/bom/pom.xml
20	Give each JAR file a module name	low	maybe use bnd-maven-plugin to generate hybrid JPMS and OSGi modules
22	Declare all direct dependencies	low/medium	use https://www.mojohaus.org/flatten-maven-plugin/

[mjacoby]

I'm not familiar with versions-maven-plugin. Is there any reason this is preferable to CI-based solutions like dependabot? I would prefer to be actively notified about new versions of a dependency which I guess is not possible with a maven plugin.

And regarding JLBP#22, how does flatten-maven-plugin ensure the required properties are actually defined? Wouldn't be maven-dependency-plugin the right tool?

[FrankSchnicke]

Here are my thoughts:

• JLBP#2: I think this an important point that we should consider before our first official release. Right now, every helper class (e.g., JsonTreeProcessor) has to be considered part of our public API. Thus, any change to this class or its function signatures would be a breaking change.
• JLBP#11: I would also be in favor of dependabot due to its native integration in GitHub.

[twebermartins]

Update 04-07-2023

Open items for V.1.0.0

JLBP #	Name	Effort	Notes
2	Minimize API surface	medium/high	to be done - V1.0.0 - For each class/method decide if public/final
7	Make breaking transitions easy	none	not done, relevant after V1.0.0 - optional: guidelines how to do breaking changes (e.g. by using @deprecated)
8	Advance widely used functionality to a stable version	none	in progress
15	Publish a BOM for multi-module projects	?	BOM or SBOM? - TBD, but relevant V1.0.0
20	Give each JAR file a module name	low	TBD - https://jlbp.dev/JLBP-20

Open Items for V1.1.0

JLBP #	Name	Effort	Notes
4	Avoid dependencies on unstable libraries and features	none	partially done, automation open
10	Maintain API stability as long as needed for consumers	none/low	TBD for V1.1.0 - concept how to maintain old versions of meta model in the future
13	Remove references to deprecated features in dependencies at the first opportunity	?	to be done for V1.1.0 - should be able to automatically scan for this, probably compiler gives a warning
16	Ensure upper version alignment of dependencies for consumers	low	TO DO after V1.1.0
17	Coordinate rollout of breaking changes	none	TBD - after V1.1.0

[in-fke]

I would also suggest to have self-contained artifactId that are "self-explaining"
e.g. instead of

dataformat-aasx
dataformat-core
dataformat-json
dataformat-parent
dataformat-xml
model

have prefix "aas4j-" for every artifact.

aas4j-dataformat-aasx
aas4j-dataformat-core
aas4j-dataformat-json
aas4j-dataformat-parent
aas4j-dataformat-xml
aas4j-model

as ArtifactIds. Imagine the artifact "spring-core" would just be called "core" - no-one could relate that it's from Spring.

[FrankSchnicke]

Good idea! We discussed this yesterday in our committer meeting and agreed on this. Cf. #195 for status and further details.