Skip to content

Latest commit

 

History

History
110 lines (75 loc) · 6.75 KB

CONTRIBUTING.md

File metadata and controls

110 lines (75 loc) · 6.75 KB
Raw

Contribution Guideline

Table of Content

New Files

  1. Commit new file(s) e.g. data models
  2. Select "Create a new branch for this commit and start a pull request."
  3. Name the branch with a descriptive name
  4. Click on "propose new file"
  5. Assign at least the workgroup manager responsible for your domain to the pull request
  6. Assign a descriptive label to the pull request
  7. Click on "create pull request"

Reporting Issues

For any issue (suggestion, bug, fix, etc.) there are fundamentally two ways an individual can contribute:

  • By helping to triage the issue: This can be done either by providing supporting details (a test case that demonstrates a bug), or providing suggestions on how to address the issue.
  • By helping to resolve the issue: Typically this is done either in the form of demonstrating that the issue reported is not a problem after all, or more often, by opening a Pull Request that changes some bit of something in Open Integration Hub in a concrete and reviewable manner.

Definition of Done

An issue is marked as done, if all of the following criteria are fulfilled:

Contributing a new data model

The OIH is an open-source platform maintained by the cloud community under the leadership of the Cloud Ecosystem. It can be run with any model which is designed and implemented by the rules and regulations listed so far.

In addition to the OIH platform itself, the OIH community also provides and maintains a number of concrete Master Data Models to be used by any OIH instance, such as models for contacts/addresses or products.

For these models, there are some further rules and regulations to follow in order to be presented in a unified way. This helps to understand and, above all, use them (i.e., implementing OIH Connectors for applications to be integrated with - respectively via - an OIH).

Organisatory

  • Create a new folder within the MasterDataModel folder and name it equally to the domain the model is provided for
  • The first page of the folder has to follow the structure of the ReadmeTemplate to guarantee a unified description of all master data models

Naming Conventions

Types and Properties

  • All type and property naming has to be in CamelCase:
    • Type names are always spelled in upper camel case (e.g., UpperCamelCaseType).
    • Property names are always spelled in lower camel case (e.g., lowerCamelCaseProperty).
  • All type and property naming has to be done in English language.
  • The prefixes OIH and *OIH* (or oih and *oih* for properties) are reserved for types and properties of OIH related Types and fields and may not be used for definitions in concrete models.__

Some attributes are used across multiple models (such as "description"). To ensure consistency across all models, some of these attributes and how they should be named wihtin OIH Data Models are listed in the following:

OIH Attribute Name Other frequently used synonyms Description
deleted deleted, removed Flag to mark a dataset as deleted or removed
type type, baseType, productType, setType, ... Used to describe the specifc object. Expection: Two or more types attributes are needed for one object
notes notes, note, additionalInformation, extraInformation, etc. Used to provide additional information for the specific object (beyond description)
url url, link Used for all kind of links associated with the specific object
value value, data Used for the acutal content of a specific object E.g. in classical pair. (Example: Contact Data (Type: Email, Value: [email protected]"))
is... All boolean attributes without is Attributes of type boolean. Should be labeled starting with is. E.g. "isProduction", "isDirect", "isExact"
tags flags, labels Attribute which assigns different descriptive buzzwords to an object

JSON-Schema

  • Schema file names are always lowercase.

  • As a seperator within file names a hyphen (-) may be used (e.g. some-schema.json).

  • The schema-ID (the $id property in a JSON-Schema) is always structured as follows:

    Example: "$id": "http://openintegrationhub.org/schemas/products/product.json"

  • Every field in a JSON-Schema must have a description property, as long as it's (even potentially) not self-explanatory.

UML Class Diagrams

  • Every OMDM must be depicted by one or more UML Class Diagrams, which illustrate the static aspect of the model. I.e., amongst others:

    • of which different OIH Data Records and entities (types) the OMDM constists,
    • how every OIH Data Record itself is composed,
    • how the OIH Data Records are related to each other,
    • which properties every entity (type) has.

  • Every OIH Data Record is defined by a Generalization relation (OIHDataRecord is modelled as the superclass of the respective sub-model, s. 5. Example: the Order aggregate).

  • Property types may, but must not be declared in the diagrams as the main purpose of these diagrams is to clarify the structure of an OMDM.

  • Following the Domain-Driven-Design all standalone objects (such as person and organization within the address model) should be coloured in yellow

  • Other attributes should be coloured in blue (See: Address model)

Clarify all further aspects of a model with diagrams and/or textually

Schemas and class diagrams only point out static aspects of a data model. Normally, there are further (e.g. dynamic) aspects of a model, that those descriptions do not point out (e.g. the conscious acceptance of redundancy). To enable ISVs and any other developers to understand and work with an OMDM,

  • all relevant aspects of a model, that are not derivable from JSON-Schemas or UML Class Diagrams have to be described textually and by further illustrations of any kind.