Comments (7)
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 |
from aas4j.
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/ |
from aas4j.
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?
from aas4j.
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.
from aas4j.
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 |
from aas4j.
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.
from aas4j.
Good idea! We discussed this yesterday in our committer meeting and agreed on this. Cf. #195 for status and further details.
from aas4j.
Related Issues (20)
- EmbeddedDataSpecifications inside XML SubmodelElements are not deserialised
- Trigger Final Release via Eclipse Foundations HOT 1
- Get Parent of Referable HOT 1
- Capitalization of class & method names changing back and forth HOT 3
- AASX containing Submodels with Files referencing files that are external to the AASX lead to a crash
- Enforce AASd-108
- interface attribute does not follow the naming pattern in Endpoint
- Allow mixed-type equals HOT 3
- Thumbnail images are not properly referenced when writing AASX files HOT 1
- File paths are written to AASX with file:// URI scheme HOT 4
- Provide formatter configuration for AAS4J HOT 1
- Opening a `.aasx` file generated by this library creates a `.aasx.cpgz` file on MacOS HOT 1
- Reading Template Asset Interfaces Description is not possible HOT 4
- Support for JSON by AASXDeserializer HOT 1
- Validation of XML UTF-8 BOM file fails
- Relationship targets do not follow the OPC HOT 3
- Make IDTA-published submodel templates loadable HOT 3
- Consider Bugfix release IDTA-01003-a: Data Spec IDs of IEC61360 template changed HOT 1
- Implement Bugfix release IDTA-0100x HOT 1
- [BUG] SAMM2AASX - incorrect serialization of Entities in Set HOT 4
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from aas4j.