Skip to main content

TRG 10.02 - KIT Content Structure

StatusCreatedPost-History
Draft12-Apr-2024Initial contribution
Active20-Nov-2025Splitted 09.01 Draft into 10.01, 10.02, 10.03 adding the new KIT 2.0 Content Structure

Why​

This TRG serves to maintain a consistent structure and ensure content quality for the KIT developers, including details for KIT content structure and KIT content owners/maintainers.

KIT, short for Keep It Together, is an open-source toolbox with comprehensive documentation that enables multiple stakeholders (Business, Solution Providers, Developers) to build interoperable applications compatible with the Eclipse Tractus-X dataspace technologies, and support the compliance with industrial standards from standarization organizations (Catena-X e.V., IDTA, ISO/DIN, EDWG, Manufacturing-X, etc.) and in some cases enable regulatory compliance.

A detailed explanation can be found here: KIT Framework

Mandatory TRGs​

For the KIT Content this two TRGs must be followed:

General Requirements​

  • A KIT must have a changelog.md following semantic versioning + the release date of Tractus-X - see TRG 1.03 - CHANGELOG.md
  • A KIT must have, at minimum, an adoption view (Sandbox stage) - see KIT Lifecycle Levels
  • KIT artifacts must be structured according to the respective views (i.e. adoption, development, operations) - see KIT Artifacts
  • Linked documents (e.g., Catena-X standards, Whitepapers) must include the current valid version (e.g. Business Partner Number (Version 2.0.0))
  • Each KIT view (business, development, ..) must include a license notice and adhere to the CY BB 4.0 license - see TRG 7.08 - Legal notice for KIT documentation (CC-BY-4.0)
  • Images must be neutral without any branding, and displayed on a. Images need to follow a the legal notice TRG - see Legal notice for non-code
  • A KIT must have a defined code owner for each industry extension - see Industry Extensions
  • A KIT must have defined code owners for kit maintenance - see KIT Maintainers & Code Owners
  • A KIT must have a SVG icon as described the TRG 10.01 and be stored in the /static/img/kits/<kit-id>/<kit-id>-raw.svg folder and be correctly licenses following the TRG 7.07.
  • A KIT logo must be included in every file in the following way (under the page title):
## Adoption View

![KIT NAME Icon](@site/static/img/kits-2.0/tx-black-kit.svg)

...

Images Storage & Licensing​

  • Any image or diagram used in the KIT documentation must be stored in a folders /resources folder.

KIT Creation Process​

The following process must be followed to create a new KIT:

Detailed Step by Step Process (click to expand)

The detailed steps for the KIT creation are defined in the KIT Getting Started Guide.

KIT Content Sections/Artifacts​

Generic Requirements for All KITs

In addition to the view-specific content below, every KIT must include:

  • Copyright Notice - Mandatory CC-BY-4.0 licensing information and contributor copyright statements at every file
  • Changelog - Version history file following semantic versioning

The views below are organized in "folders" so that its sections are harmonized and the content from each view remains flexible.

ViewsStakeholdersContent
Adoption ViewBusinessBusiness Value, Motivation, Vision, Mission, Whitepapers, Semantic Models, Standards, Tutorials, Explanations why this use case is important, Context
Development ViewDevelopersArchitectsOverall Architecture, Reference Implementations, API specifications, Policies, Algorithms, Functional Requirements, Sequence Diagrams, Process, Architecture Guidelines
Operator ViewOperatorsService ProvidersNon-Functional Requirements, Security Requirements, Recommendations, Restrictions
DocumentationAny StakeholderExtra Documentation and Links
Success StoriesOperatorsService ProvidersBusinessSuccess Stories from Reference Implementations that used this KIT. Open Source and COTS.
Industry ExtensionsDataspace AdoptersOne Folder per Industry. Extends the contents from the other views with regards to a specific industry and affiliated dataspace standards/requirements

A deep dive explanation of each section can be found at the KIT Framework Documentation guideline.

Sections File/Folder Structure​

The following folder structure represents a complete KIT template with all required sections and views (example of a KIT folder structures):

docs-kits/kits/
  <kit-name>/
    ├── README.md                          # Main KIT overview and quick start guide
    ├── CHANGELOG.md                       # Version history following semantic versioning
    ├── adoption-view/
    │   ├── _category_.json
    │   └── adoption-view.md               # Business value, use cases, policies, standards
    ├── development-view/
    │   ├── _category_.json
    │   └── development-view.md            # Architecture, API specs, semantic models, tutorials
    ├── operations-view/
    │   ├── _category_.json
    │   └── operations-view.md             # Deployment guides, monitoring, security, troubleshooting
    ├── industry-extensions/
    │   ├── _category_.json
    │   ├── automotive/
    │   │   ├── _category_.json
    │   │   └── overview.md                # Catena-X automotive-specific content
    │   └── shop-floor/
    │       ├── _category_.json
    │       └── overview.md                # Manufacturing-X shop-floor-specific content
    ├── success-stories/
    │   ├── _category_.json
    │   └── my-app.md                      # Template for implementation success stories
    ├── documentation/
    │   ├── _category_.json
    │   ├── github-repository.md           # Link to GitHub repository
    │   ├── api-documentation.md           # Link to API documentation
    │   ├── community-support.md           # Link to community support channels
    │   └── related-standards.md           # Links to related standards
    └── resources/
        └── img/                           # KIT-specific images and diagrams
        └── ...
Template Available

A complete KIT template with all required files and structure is available at: /docs-kits/kit-template/

This template includes detailed guidelines and examples for each section.

Only per view​

In case a VIEW has only one file it shall be described in this way as a md or mdx file insice of its respective folder (using the same name of the view):

/docs-kits/kits/
  <kit-name>/
    adoption-view/
        adoption-view.md

Multiple files per view​

In case a VIEW has multiple files it shall be described in this way as a folder with multiple md or mdx files (main views have the same name as the folder):

/docs-kits/kits/
  <kit-name>/
    development-view/
        architecture.md
        deployment-view.mdx
    operation-view/
        operation-view.md
        monitoring.md
    ...

KIT Maintainers & Code Owners​

How to become a Committer?
Contributor & Committer Guide
Expert Review

In case the content needs expert review, is recommended for the code owner/committer to request reviews from the relevant experts in the community before merging the PR. This applies for any KIT Lifeclycle status.

The CODEOWNERS file must follow the structure described at the GitHub documentation.

No company/organization can be added as a code owner, only a contributor with a GitHub account. Ownership and Copyright for organizations are described in the following TRG 7.08 - Legal notice for KIT documentation (CC-BY-4.0)

Example:

# In this example, @doctocat owns any file in the `/docs-kits/kits/connector-kit/`
# directory, it will be notified of any changes to files in that directory, if he is a committer.
# subdirectories.
/docs-kits/kits/connector-kit/ @doctocat
Code Owner Responsibilities

If the committer is the one contributing the KIT content, when merging the PRs they shall ensure that:

  • All required documentation sections are complete and follow the KIT structure described in the KIT 10.xx TRGs
  • Copyright notices and licensing information are properly included
  • The changelog is updated with accurate version information
  • All linked resources and references are valid and up-to-date

Industry Extensions​

The following rules apply for the industry extension section:

  • Only releavant/updated content for the specific industry extension should be included, in case legacy content is needed, the content can be kept previous versions of the KIT or archived at the large-files repository.
  • A code owner must be set by adding to the CODEOWNERS at the specific industry extension folder path, the file is located here .github/CODEOWNERS.

The CODEOWNERS file must follow the structure described at the GitHub documentation.

No company/organization can be added as a code owner, only a contributor with a GitHub account. Ownership and Copyright for organizations are described in the following TRG 7.08 - Legal notice for KIT documentation (CC-BY-4.0)

Example:

# In this example, @doctocat owns any file in the `/docs-kits/kits/connector-kit/industry-extensions/automotive`
# directory, it will be notified of any changes to files in that directory, if he is a committer.
# subdirectories.
/docs-kits/kits/connector-kit/industry-extensions/automotive/ @doctocat

When a change is done to the industry extension folder, please contact the code owner via the available channels (Matrix Chat, Mailing List, etc.) to inform them about the change.

Alignment Mechanisms​

To ensure the quality and consistency of KITs, the following alignment mechanisms are in place, not all channels need to be activated:

Main KIT Alignment Channels​

ChannelPurposeLink
Alignment DayQuarterly refinement sessionsAlignment Days Docs
Open Planning DayQuarterly open planning sessionsOpen Planning Days Docs
Matrix ChatDaily discussions & support#tractusx-kits:matrix.eclipse.org
KIT Community Office HoursWeekly alignment meetingsJoin Meeting

Support KIT Alignment Channels​

ChannelPurposeLink
KIT Office Hour KanbanDevelopment items trackingGithub Project
Matrix ChatDaily discussions & support#tractusx-kits:matrix.eclipse.org
GitHub IssuesTechnical issues & bugsCreate Issue
SIG-ReleaseOfficial KIT Release Trackingeclipse-tractusx/sig-release
KIT DiscussionsOffical KIT Proposal and Discussion LocationKIT Discussions

In case a change to a existing KIT is planned, it is recommended to use the KIT Discussions or GitHub Issues to discuss the change with the community before starting the implementation. This will help to gather feedback and ensure alignment with other KIT developers.