Skip to content

Doc: update Traceability KIT documentation for release 26.09 - #1583

Open
JK181196 wants to merge 6 commits into
eclipse-tractusx:mainfrom
JK181196:main
Open

Doc: update Traceability KIT documentation for release 26.09#1583
JK181196 wants to merge 6 commits into
eclipse-tractusx:mainfrom
JK181196:main

Conversation

@JK181196

Copy link
Copy Markdown

Description

Pre-review checks

Please ensure to do as many of the following checks as possible, before asking for committer review:

@JK181196 JK181196 changed the title Doc:_update Traceability KIT documentation for release 26.09_ Doc: update Traceability KIT documentation for release 26.09_ Aug 24, 2026
@JK181196 JK181196 changed the title Doc: update Traceability KIT documentation for release 26.09_ Doc: update Traceability KIT documentation for release 26.09 Aug 24, 2026
@stephanbcbauer stephanbcbauer added this to the 26.09 milestone Sep 3, 2026
@stephanbcbauer
stephanbcbauer requested a lite review from Copilot September 3, 2026 11:34

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

There are multiple confirmed documentation consistency/formatting issues (aspect naming, lifecycle operation alignment, and changelog list formatting) that should be fixed before merge.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Hi, I’m the KIT Master Builder — your Eclipse Tractus-X KIT architect and reviewer.

This PR updates the Traceability KIT (versioned docs under version-26.06) to align the Block Notification documentation with the standalone standard by switching from a status-model description to a lifecycle-based concept, and refreshes Special Characteristics references and the Traceability KIT changelog for release 26.09.

Changes:

  • Reworked Block Notification documentation across Adoption/Architecture/Development views toward a lifecycle-based interaction model.
  • Updated Special Characteristics / SpecialCharacteristicMeasurement references (incl. version bump to 3.0.0 and manufacturer BPN field naming in examples).
  • Added a new 9.0.0 changelog entry for release 26.09.
File summaries
File Description
docs-kits_versioned_docs/version-26.06/kits/traceability-kit/software-development-view/parts/aspect-models.mdx Updates Special Characteristics aspect model references (v3.0.0) and example field naming; some naming/link consistency needs adjustment.
docs-kits_versioned_docs/version-26.06/kits/traceability-kit/software-development-view/app-provider.mdx Replaces the previous status-model explanation with lifecycle-based Block Notification text; needs consistency with Architecture View (Feedback op + heading).
docs-kits_versioned_docs/version-26.06/kits/traceability-kit/changelog.mdx Adds a 9.0.0 entry for release 26.09; list formatting and one identifier name need correction.
docs-kits_versioned_docs/version-26.06/kits/traceability-kit/architecture-view.mdx Updates Block Notification interaction description and adds the Special Characteristics aspect model to the overview; one aspect name is inconsistent with other views.
docs-kits_versioned_docs/version-26.06/kits/traceability-kit/adoption-view.mdx Refines Block Notification description in the Adoption View to match the updated concept.
Review details
  • Files reviewed: 5/5 changed files
  • Comments generated: 5
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

- Aspect model ["SoftwareInformation"](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main)
- Aspect model ["CertificateSigningRequests"](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main)
- Aspect model ["ZeroKmFailure"](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main)
- Aspect model ["SpecialCharacteristicsMeasurement"](https://github.com/eclipse-tractusx/sldt-semantic-models/tree/main)
Comment on lines +18 to +38
- **Adoption View:**
- Reworked Block Notification description to align with the standalone Block Notification standard
- Added clarification regarding temporary compatibility with legacy Quality Notifications

- **Architecture View:**
- Simplified Block Notification interaction concept
- Replaced status-model based description with lifecycle-based interaction model (Create, Update, Remove)
- Removed outdated blocking scenarios and status-model explanations
- Removed references to deprecated block notification state transitions
- Updated references to the standalone Block Notification standard
- Added reference to the Special Characteristics standard
- Updated Special Characteristics aspect model references

- **Development View:**
- Reworked Block Notification documentation to align with the standalone Block Notification standard
- Simplified lifecycle and API descriptions
- Removed obsolete status-model specific implementation guidance
- Updated usage policy guidance for Block Notifications
- Updated Special Characteristics aspect model version to 3.0.0
- Added reference to the Special Characteristics standard
- Replaced `manufacturerID` with `manufacturerBpn` in the Special Characteristics examples and data model descriptions
Comment on lines 47 to +51
### Block Status Model

In order to track the blocking process in the Catena X network, a defined status model is used for each part of the block notification:
![Block Status Model](../assets/block-notification-state-model.svg)
Block Notifications follow a lifecycle-based interaction model consisting of:

- ACTIVE means that the part has been identified as a damaged and safety-critical part and must therefore be blocked on the customer side.
- PART_BLOCKED is used when the recipient has received the block notification and actually blocks / sorts out the damaged parts as a measure.
- CANCELED serves as the update status of the component originally identified to be blocked if the supplier subsequently determines that the original part does meet safety requirements, is not damaged or that the information was sent by mistake. This status can also be set by the manufacturer if, after an (initial) analysis, the part does not require a block.
- **Create** initiates a new Block Notification.
| | SoftwareInformation | 1.0.0 | | Traceability | N/A |
| | CertificateSigningRequests | 1.0.0 | | Traceability | N/A |
| | SpecialCharacteristics | 1.0.0 | | Traceability | N/A |
| | SpecialCharacteristics | 3.0.0 | | Traceability | CX-0163 Special Characteristics |
#### Aspect Model in GitHub

- **Version 2.0.0**: [GitHub Repository](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.special_characteristics.measurement/2.0.0/)
- **Version 3.0.0**: [GitHub Repository](https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.special_characteristics.measurement/3.0.0/)
@stephanbcbauer

Copy link
Copy Markdown
Member

👋 Hi! I'm the KIT Master Builder — your Eclipse Tractus-X KIT architect and reviewer. I've reviewed the current branch changes around the new eSDScom KIT and here is my feedback.

✅ What I like

  • The KIT structure is solid and consistent with the repo pattern: adoption-view, development-view, changelog.md, and a dedicated resources/ folder.
  • The legal headers and ## NOTICE footer are in place, which matches the spirit of TRG 7.07 and the repo’s KIT documentation expectations.
  • The Kit3DLogo import/render pattern is correctly used.

⚠️ Changes I would fix before merging

  • Broken route in the master data:

    • In data/kitsData.js, the KIT is registered with:
      • /docs-kits/next/kits/esdscom-kit/adoption-view
    • In this repo, there is no docs-kits/next folder at all; the actual docs structure is docs-kits/kits/....
    • This means the gallery entry and navigation likely point to a 404 page. This is the most concrete issue I found.
    • Per the KIT conventions and the folder structure in the project, this should point to the live docs path, not a non-existent version folder.
  • Sidebar alphabetical ordering:

    • In sidebarsDocsKits.js, the eSDScom KIT block is placed after Environmental and Social Standards KIT.
    • The repo expects KIT categories to be ordered alphabetically by label. If this is enforced, eSDScom KIT should be placed before Environmental and Social Standards KIT.
  • Copyright inconsistency:

    • docs-kits/kits/esdscom-kit/changelog.md uses Copyright(c) 2025 while the other KIT pages use 2026.
    • The year should be consistent with first creation and the file’s metadata. This matters for legal clarity and TRG 7.07 compliance.

💡 Suggestions

  • I’d also sanity-check the route and generated index path once more across the full KIT gallery and sidebar because a wrong route here blocks discoverability even when the content is otherwise correct.
  • If the intention is a development-only “next” docs version, it should be created in the same pattern as the other versioned docs. Otherwise, keep it on the normal /docs-kits/kits/... path.

📋 Summary

  • The content is promising and mostly aligned with the KIT template.
  • The route issue is the real blocker. The rest are polish and compliance details I’d fix before merge.

@stephanbcbauer stephanbcbauer left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review started by @ther3sa and @stephanbcbauer

  • IMPORTANT: @JK181196 please sign the ECA... without signed ECA, we are not allowed to merge the PR @ther3sa FYI
  • the title of the PR describes changes for 26.09 but the changes are done in the versioned section for 26.06 -> this means the changes are not visible for the current version and the following -> is this intended?
  • Is you company listed in the NOTICE section?
  • PLease have a look at the findings from CoPilot and KIT Master Builder

THX

@github-project-automation github-project-automation Bot moved this from Inbox to Todo in Tractus-X Webpage Sep 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

4 participants