feat(trg):new trg for kits #626
Conversation
There was a problem hiding this comment.
Haven't gone through all the content yet, but already found some typos and grammatical issues.
Also, I think we should move some of the contents vom this PR to a separate KIT section, instead of defining them as TRG.
Another critical topic from my point of view is the versioning part. See comments for that
There was a problem hiding this comment.
I think this is general information, that would be better placed in a "KIT - Getting started" section. Maybe even as item in the "KITs" menu.
If someone would look for this kind of information, I bet they would first look at the KIT menu and not necessarily in release guidelines
There was a problem hiding this comment.
As I remember a discussion with Angelika and Daniel - we said to dissolve the KIT guidance section and move the stuff to TRGs to not have a separate section in the developer hub. We can have a link from the KIT menu or main page to the TRG. But the KIT main section should be for solution provider and data prosumer, not for teams that want to publish their stuff in a KIT.
There was a problem hiding this comment.
Ok, I can see that. I would still move it at least to a dedicated menu in "Developer Hub".
"What is a KIT" is definitely not a release guideline from my point of view.
I also still think that data provider and consumers could benefit from a definition for KITs.
It is also partly already present here: https://eclipse-tractusx.github.io/developer
So again, I would link to that instead of re-defining. If there is missing information, I would enhance the description for the KIT entry page
|
|
||
| Prerequisites: [Tractus-X getting started](https://eclipse-tractusx.github.io/docs/oss/getting-started) | ||
|
|
||
| - **TRG 8.02 KIT Graduation** A KIT is always structured the same way and follows three graduation stages |
There was a problem hiding this comment.
As this whole TRG, this specific headline suggests, that we should thing about a "KIT - Getting started" section to introduce everyone to the concept of KITs
|
|
||
| ## Why | ||
|
|
||
| KIT means Keep It Together. A KIT contains all the artefacts that are relevant to participate in the Catena-X data space as an operator, data provider or solution / app provider. These stakeholders have one place with all the information they need. For example an explaination of an API, the specification of it and the deployment instructions. The target of a KIT should be that you have no need to visit any other information source. |
There was a problem hiding this comment.
Typo "artifacts" instead of "artefacts",
Typo "explanation" instead of "explaination"
"goal ..." or "aim ..." instead of "target of a KIT"?
|
|
||
| KIT means Keep It Together. A KIT contains all the artefacts that are relevant to participate in the Catena-X data space as an operator, data provider or solution / app provider. These stakeholders have one place with all the information they need. For example an explaination of an API, the specification of it and the deployment instructions. The target of a KIT should be that you have no need to visit any other information source. | ||
|
|
||
| A detailed explaination can be found here: |
There was a problem hiding this comment.
Typo "explanation" instead of "explaination"
| - **TRG 8.03 KIT Artefacts** Each of the artefacts in a KIT are explained with examples | ||
| - **TRG 8.04 KIT Structure** The project structure inside the repository and the adjustments that are needed for Docusaurus | ||
|
|
||
| ## Support |
There was a problem hiding this comment.
Also something, that should move to a "KIT - Getting started" section.
|
|
||
| During the first publication / release of the incubating phase, the major version must be 0. This means that the version of a KIT that is not yet graduated always has the format 0.x.y. The minor component is incremented exactly when an artifact is completed and the patch component is incremented for all other changes. | ||
|
|
||
| As soon as a KIT moves to the second release and got published / released once it´s version is set to 1.0.0. - in general the KITS follow semantic versioning. |
There was a problem hiding this comment.
This is absolutely NOT following semantic versioning
|
|
||
| ### Graduated Phase | ||
|
|
||
| Upon reaching the Graduation Phase, a KIT is production ready and got verified by a solution provider or data prosumer. Since the KITs are maintained and further developed by the community, changes can be made that result in an incompatibility. |
There was a problem hiding this comment.
I guess it should be "consumer" instead of "prosumer"
I also don't really get, what this phase it is about. What is "production ready"? How does an external "verification" work? Is there any transparent process for that?
What is the goal behind "developed by the community, so there can be incompatibilities" sentence?
|
|
||
| ## ADOPTION VIEW | ||
|
|
||
| The adoption view gives a general introduction to the KIT. Provide an understanding to an OEM, a solution provider or data provider whats the main purpose, which industry problem is this KIT solving. |
There was a problem hiding this comment.
Better. "It aims to provide insights to industry problems, the KIT is addressing"
|
|
||
| The vision describes the strategic objectives of a KIT and how it aims to inspire solution providers. | ||
|
|
||
| Deliverables: |
There was a problem hiding this comment.
I would avoid "Deliverables". TRGs should describe quality criteria, guidelines and rules.
suggestion:
"Answers, the 'Vision & Mission' statement of a KIT must provide"
|
|
||
| The business value describes the benefits for an service provider by using a KIT in order to create a commercial or non-profit solution for the Catena-X marketplaces. | ||
|
|
||
| Deliverable: |
There was a problem hiding this comment.
Again: Would avoid "Deliverable"
| - Integration of the OpenAPI file | ||
| - Use case examples for the API endpoints and how to use them | ||
|
|
||
| `Example from DataChain KIT:` The API of the Item Relationship Service (IRS) for retrieving item graphs along the value chain of CATENA-X partners. |
There was a problem hiding this comment.
"Catena-X" instead of "CATENA-X"
| - Usage examples | ||
| - More explaination on how to use the API in different scenarios | ||
|
|
||
| ## Operations View |
There was a problem hiding this comment.
I think there is a TRG about architecture documentation planned, that will describe quality criteria for an "admin guide".
we should keep that in mind and probably link to it as soon as it is available.
Especially KITs, that target Tractus-X apps should link to the product docs instead of duplicating content on a website
|
|
||
| ## Project Structure | ||
|
|
||
| Following our project structure, the collection of our KITs documentation is developed in the `./docs-kits/kits` folder, where each KIT is a subfolder called by its name for organisation purposes. The `Data Chain KIT`, for example, is defined here: `./docs-kits/kits/Data Chain Kit`. |
There was a problem hiding this comment.
I would really appreciate, if we could stop recommending spaces in directory names. We build a website from this source and always have to fight with URL encoding. You can also see that in some of the links provided in this documentation.
My suggestion would be kebab-case, since this seems to be the one, currently used the most in this repo.
so /docs-kits/kits/data-chain-kit instead of /docs-kits/kits/Data Chain Kit
| - Documentation -> `page_documentation.md` | ||
| - Software Development View/ | ||
| - Specification -> `page_software-development-view.md` | ||
| - OpenAPI definition/ |
There was a problem hiding this comment.
OpenAPI definitions are moving to SwaggerHub, so I would not mention any local structure here
| - Another OpenAPI definition/ | ||
| - ... | ||
|
|
||
| ## Steps to add a NewKit documentation |
There was a problem hiding this comment.
Also better to move to "KITs - Getting started".
This is also a bit too "low level" in my opinion. I think describing the necessary files is enough. Everyone contributing to eclipse-tractusx should now how to create directories and files.
And even if not, we are always happy to provide onboarding.
"Click here.. type 'abc'.." kind of documentation seems to be unnecessarily verbose to me
| └──page_software-development-view.md | ||
| ``` | ||
|
|
||
| 6. To generate the `OpenAPI` based documentation of your KIT, please consult the [Plugins section](/docs/website-guidelines/wiki#plugins) to configure your instance of the `Docusaurus-OpenAPI-Docs` in the `docusaurus.config.js`. |
There was a problem hiding this comment.
Wrong. Superseded by SwaggerHub, like mentioned
|
|
||
| To know more about the `NavBar` options and how to implement this and other features in it please check the [Docusaurus - NavBar Documentation](https://docusaurus.io/docs/2.2.0/api/themes/configuration#navbar-dropdown) | ||
|
|
||
| ## Important to know |
There was a problem hiding this comment.
Also move to "KIT - Getting started"
|
Hi @maximilianong,
|
There was a problem hiding this comment.
In addition to Sebastian's comments, Section TRG 8 is used in the meantime for security-related matters.
|
We will close this now - but we worked on your comments and will do a new PR with the changes. |
Description
This contains 4 new .md files that will work as TRG for KITs describing how a KIT can be initiated, what stages a KIT can go through and what artifacts for a KIT need be delivered.