From 99b31d7b108e8d06908e29a630a23795abe52e36 Mon Sep 17 00:00:00 2001 From: Sven Erik Jeroschewski Date: Mon, 5 Dec 2022 11:30:31 +0100 Subject: [PATCH] adds issue and PR templates --- .../model_deprecation_request.md | 16 +++++++++ .../ISSUE_TEMPLATE/model_update_request.md | 19 ++++++++++ .github/ISSUE_TEMPLATE/new_model_request.md | 24 +++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 35 +++++++++++++++++++ README.md | 5 +-- 5 files changed, 97 insertions(+), 2 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/model_deprecation_request.md create mode 100644 .github/ISSUE_TEMPLATE/model_update_request.md create mode 100644 .github/ISSUE_TEMPLATE/new_model_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/model_deprecation_request.md b/.github/ISSUE_TEMPLATE/model_deprecation_request.md new file mode 100644 index 00000000..ed535dcd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/model_deprecation_request.md @@ -0,0 +1,16 @@ +--- +name: Model Deprecation Request +about: File a request to mark an existing model as deprecated +title: '[Model Deprecation]: ' +labels: deprecate + +--- + +## Update Reason + + +## MS1 Criteria + +- [ ] The model that should be deprecated exists and is not deprecated already +- [ ] The respective model does not affect existing use cases (aspect is either used in higher versions or replaced by a different aspect) +- [ ] A shared aspect, which will be deprecated, is not used by any released aspect model diff --git a/.github/ISSUE_TEMPLATE/model_update_request.md b/.github/ISSUE_TEMPLATE/model_update_request.md new file mode 100644 index 00000000..227f0974 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/model_update_request.md @@ -0,0 +1,19 @@ +--- +name: Model Update Request +about: File a request to update an existing model +title: '[Model Update]: ' +labels: update + +--- + +## Update Reason + + +## MS1 Criteria + +- [ ] The model that should be updated exists +- [ ] The referenced use case exists +- [ ] The potential updates are discussed with all stakeholders +- [ ] The potential update will be either + - [ ] backward compatible or + - [ ] a (chain of) migration strategy(-ies) from all non-deprecated previous versions to the new model will be developed diff --git a/.github/ISSUE_TEMPLATE/new_model_request.md b/.github/ISSUE_TEMPLATE/new_model_request.md new file mode 100644 index 00000000..ca440e51 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new_model_request.md @@ -0,0 +1,24 @@ +--- +name: New Model Request +about: File a request for a new Catena-X model +title: '[New Model]: ' +labels: creation + +--- + +## Model Description + + +## Relevant Standards + + +## Example Data + + +## MS1 Criteria + +- [ ] The proposed aspect model does not exist already +- [ ] The proposed aspect model does not extend an existing aspect but introduces completely new functionality +- [ ] The proposal references a Catena-X use case +- [ ] Relevant standards are mentioned/linked +- [ ] A first draft of the data structure is provided in an example diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..73f4f41a --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,35 @@ +## Description + + + --> + +Closes # + + +## MS2 Criteria +(to be filled out by PR reviewer) +- [ ] the model **validates** with the BAMM SDS SDK in the version specified in the Readme.md of this repository by the time of the MS2 check (e.g., 'java -jar bamm-cli.jar -i \ -v ). The BAMM CLI is available [here](https://openmanufacturingplatform.github.io/sds-documentation/sds-developer-guide/dev-snapshot/tooling-guide/bamm-cli.html) and in [GitHub](https://github.com/OpenManufacturingPlatform/sds-sdk/releases) +- [ ] use **Camel-Case** (e.g., "MyModelElement" or "TimeDifferenceGmtId", when in doubt follow https://google.github.io/styleguide/javaguide.html#s5.3-camel-case) +- [ ] the identifiers for all model elements **start with a capital letter** except for properties +- [ ] the identifier for **properties starts with a small letter** +- [ ] all model elements **at least contain the fields "name" and "description"** in English language. +- [ ] **no duplicate names or preferredNames** within an Aspect (e.g. a Property and the referenced Characteristic should not have the same name) +- [ ] the versioning in the URN **follows semantic versioning**, where minor version bumps are backwards compatible and major version bumps are not backwards compatible. +- [ ] use **abbreviations only when necessary** and if these are sufficiently common +- [ ] **avoid redundant prefixes in property names** (consider adding properties to an enclosing Entity or even adapt the namespace of the model elements, e.g., instead of having two properties `DismantlerId` and `DismantlerName` use an Entity `Dismantler` with the properties `name` and `id` or use a URN like `io.catenax.dismantler:0.0.1`) +- [ ] fields `preferredName` and `description` are not the same +- [ ] **`preferredName` should be human readable** and follow normal orthography (e.g., no camel case but normal word separation) +- [ ] name of aspect is singular except if it only has one property which is a Collection, List or Set. In theses cases, the aspect name is plural. +- [ ] units are referenced from the BAMM unit catalog whenever possible +- [ ] **use constraints** to make known constraints from the use case explicit in the aspect model +- [ ] when relying on **external standards**, they are referenced through a **"see"** element +- [ ] all properties with an [simple type](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/v1.0.0/datatypes.html) have an example value + +## MS3 Criteria +(to be filled out by semantic modeling team before merge to main-branch) +- [ ] All required reviewers have approved this PR (see reviewers section) +- [ ] The new aspect (version) will be implemented by at least one data provider +- [ ] The new aspect (version) will be consumed by at least one data consumer +- [ ] There exists valid test data +- [ ] In case of a new (incompatible) major version to an existing version, a migration strategy has been developed +- [ ] The model has at least version '1.0.0' \ No newline at end of file diff --git a/README.md b/README.md index b59f4e60..434ccae8 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ # Aspect Models for Eclipse Tractus-X Semantic Layer (SLDT) The repository contains the aspect models based on [BAMM](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/snapshot/index.html) for the Tractus-X project for Catena-X. +**Currently, we assume the usage of the version 2.0.6 of the BAMM-CLI**. + + # Using the models The models can locally be processed with the [BAMM CLI](https://openmanufacturingplatform.github.io/sds-documentation/sds-documentation/index.html). It allows you to generate different artifacts (diagrams, example payload, java class files) out of it. -Currently, we assume the usage of the version 2.0.6 of the BAMM-CLI. - # Status of model Each model has its life cycle and can thus have a different status. This information always corresponds to a specific version of the model. To indicate the state of the model version in Git, one creates a file with the name `metadata.json` and places it in the same directory as the corresponding model file. It is also possible to load the models into the [Semantic Hub](https://github.com/eclipse-tractusx/sldt-semantic-hub) which has a corresponding state management. An example `metadata.json` looks like this: