Feature/393 readme improvements

.config/README.md

@@ -0,0 +1,19 @@
+
+[[Back to main IRS README](../README.md)]
+
+# .config Folder
+
+This folder contains configuration, rules and suppression files for code quality check tools etc.
+
+| File / Folder               | Description                                                                               | Further information                                                                                                    |
+|-----------------------------|-------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
+| spectral                    |                                                                                           |                                                                                                                        | 
+| .trivyignore                | Ignore file for [Trivy](https://trivy.dev/) to configure which false positives to ignore. | [Trivy ignorefile documentation](https://aquasecurity.github.io/trivy/v0.49/docs/configuration/filtering/#trivyignore) |
+| checkstyle.xml              | [Checkstyle](https://checkstyle.sourceforge.io) configuration.                            | [Checkstyle configuration](https://checkstyle.sourceforge.io/config.html)                                              |
+| checkstyle-suppressions.xml | [Checkstyle](https://checkstyle.sourceforge.io/) suppressions.                            | [Checkstyle suppressions documentation](https://checkstyle.sourceforge.io/filters/suppressionfilter.html)              |
+| irs.header                  | Copyright header definition for the checkstyle module RegexpHeader.                       | see checkstyle.xml file                                                                                                |
+| owasp-suppressions.xml      | [OWASP dependendy check](https://owasp.org/www-project-dependency-check/) suppressions.   | [OWASP suppressions documentation](https://jeremylong.github.io/DependencyCheck/general/suppression.html)              |
+| pmd-rules.xml               | [PMD Source Code Analyzer](https://pmd.github.io/) rules.                                 | [PMD rules documentation](https://pmd.github.io/pmd/pmd_userdocs_making_rulesets.html)                                 |
+| spotbugs-excludes.xml       | [Spotbugs](https://spotbugs.github.io/) excludes.                                         | [Spotbugs excludes documentation](https://spotbugs.readthedocs.io/en/stable/filter.html)                               |
+
+

AUTHORS.md

@@ -16,6 +16,7 @@ The following people have contributed to this repository:
 - Sebastian Bezold, Mercedes Benz AG, https://github.com/SebastianBezold
 - Zied Belkhiria, MHP, https://github.com/Zied-Belkhiria-Mhp
 - Adam Bugajewski, doubleSlash Net-Business GmbH, https://github.com/ds-ext-abugajewski
+- Pawel Sosnowski, doubleSlash Net-Business GmbH, https://github.com/ds-psosnowski
 - Matthias Fischer, doubleSlash Net-Business GmbH, https://github.com/dsmf
 - Sebastian Ceronik, doubleSlash Net-Business GmbH, https://github.com/ds-ext-sceronik
 - Maximilian Wesener, doubleSlash Net-Business GmbH, https://github.com/ds-mwesener

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+_**For better traceability add the corresponding GitHub issue number in each changelog entry, please.**_
+
 ## [Unreleased]
 ### Added
 - DigitalTwinRegistryCreateShellService in irs-registry-client for creating shells in DTR directly

CONTACT.md

@@ -0,0 +1,7 @@
+
+# Getting in Touch
+
+Contact the [project developers](AUTHORS.md) via the project's "dev" list.
+
+* [Mailing List](https://accounts.eclipse.org/mailing-list/tractusx-dev)
+* [Eclipse Matrix Chat](https://chat.eclipse.org/#/room/#tractusx-irs:matrix.eclipse.org)

CONTRIBUTING.md

@@ -7,12 +7,13 @@ Thanks for your interest in this project.
 2. [Developer resources](#developer-resources)
 3. [Eclipse Development Process](#eclipse-development-process)
 4. [Eclipse Contributor Agreement](#eclipse-contributor-agreement)
-5. [General contribution to the project](#general-contribution-to-the-project)
-6. [Contributing as a Consultant](#contributing-as-a-consultant)
-7. [Contributing as a Developer](#contributing-as-a-developer)
+5. [Code of Conduct](#code-of-conduct)
+6. [General contribution to the project](#general-contribution-to-the-project)
+7. [Contributing as a Consultant](#contributing-as-a-consultant)
+8. [Contributing as a Developer](#contributing-as-a-developer)
 9. [Contact](#contact)
 
-## Project description
+## Project Description
 
 The companies involved want to increase the automotive industry's
 competitiveness, improve efficiency through industry-specific cooperation and
@@ -26,9 +27,8 @@ Catena-X alliance focusing on parts traceability.
 
 * https://projects.eclipse.org/projects/automotive.tractusx
 * https://github.com/eclipse-tractusx/item-relationship-service
-* https://github.com/catenax-ng/tx-item-relationship-service
 
-## Developer resources
+## Developer Resources
 
 Information regarding source code management, builds, coding standards, and
 more.
@@ -63,6 +63,10 @@ fulfills the DCO's requirement that you sign-off on your contributions.
 For more information, please see the Eclipse Committer Handbook:
 https://www.eclipse.org/projects/handbook/#resources-commit
 
+## Code of Conduct
+
+See [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md).
+
 ## Eclipse Dependency License Check
 
 In case of new dependencies or version updates, it might be necessary to have the new library checked and accepted by the Eclipse foundation. Do create new tickets for this, you can use this command:
@@ -72,20 +76,23 @@ mvn org.eclipse.dash:license-tool-plugin:license-check -Ddash.iplab.token=$ECLIP
 
 For more information on the tool and how to acquire the token, check https://github.com/eclipse/dash-licenses.
 
-## General contribution to the project
+## General Contribution to the Project
+
+General contributions e.g. contributions to improve documentation are welcome.
+If you need ideas for contributions, you can check the following links:
+- [open documentation stories](https://github.com/orgs/eclipse-tractusx/projects/8/views/4?filterQuery=label%3Adocumentation++status%3Ainbox%2Cbacklog)
+- [discussion page concerning documentation improvements](https://github.com/eclipse-tractusx/item-relationship-service/discussions/407)
 
 
 ## Contributing as a Consultant
 
 ### Conceptual work and specification guidelines
-1. The prerequisite for a concept is always a github issue that defines the business value and the acceptance criteria that are to be implemented with the concept
+1. The prerequisite for a concept is always a GitHub issue that defines the business value and the acceptance criteria that are to be implemented with the concept
 2. Copy and rename directory /docs/#000-concept-name-template /docs/#<DDD>-<target-name>
-3. Copy file /docs/Concept_TEMPLATE.md into new directory  /docs/#<DDD>-<target-name>
+3. Copy the template file [/docs/concept/TEMPLATE_Concept.md](docs/concept/TEMPLATE_Concept.md) into new directory `/docs/#<DDD>-<target-name>`.
 
 ### Diagrams
-PlantUML and Mermaid is used for conceptual work.
-https://mermaid.js.org/
-https://plantuml.com/
+[PlantUML](https://plantuml.com/) and [Mermaid](https://mermaid.js.org/) is used for conceptual work.
 
 
 #### PlantUML 
@@ -111,7 +118,8 @@ sequenceDiagram
 
 ## Contributing as a Developer
 
-### Commit messages
+### Commit Messages
+
 The commit messages have to match a pattern in the form of:  
 ``< type >(scope):[<Ticket_ID>] < description >``  
 where type is: `build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test`
@@ -122,14 +130,15 @@ Example:
 
 Detailed pattern can be found here: [commit-msg](local/development/commit-msg)
 
-#### How to use
+#### How to Use
 ```shell
 cp local/development/commit-msg .git/hooks/commit-msg && chmod 500 .git/hooks/commit-msg
 ```
 
 For further information please see https://github.com/hazcod/semantic-commit-hook
 
-### Code formatting 
+### Code Formatting
+
 #### Deprecated soon:
 Please use the following code formatter: [.idea/codeStyles](.idea/codeStyles)
 
@@ -150,19 +159,23 @@ The plugin will be disabled by default. To enable it in the current project, go
 More info:  
 https://github.com/google/google-java-format/blob/master/README.md#intellij-jre-config
 
-### Create a release
-
-1. Choose a release version. Use semantic versioning! Create a respective branch e.g. `chore/prepare-release-2.6.1`.
-2. Add release notes for new version in [CHANGELOG.md](CHANGELOG.md) and [charts/irs-helm/CHANGELOG.md](charts/irs-helm/CHANGELOG.md) (e.g. https://github.com/catenax-ng/tx-item-relationship-service/pull/328)
-3. Update [COMPATIBILITY_MATRIX.md](COMPATIBILITY_MATRIX.md) (see [catena-x-environments](https://github.com/catenax-ng/tx-item-relationship-service/tree/catena-x-environments/charts/irs-environments))
-4. Create pull request and merge to main
+### Create a Release
+
+1. Choose a release version using [semantic versioning](https://semver.org/spec/v2.0.0.html)
+   and create a corresponding branch according to the template: `chore/prepare-release-x.x.x`.
+2. Add release notes for new version in [CHANGELOG.md](CHANGELOG.md)
+   and [charts/irs-helm/CHANGELOG.md](charts/irs-helm/CHANGELOG.md)
+   (for an example [see here](https://github.com/eclipse-tractusx/item-relationship-service/pull/429))
+   - Check if the changelog entries for the release are complete.
+   - Add the corresponding GitHub issue numbers to each entry if missing.
+3. Update [COMPATIBILITY_MATRIX.md](COMPATIBILITY_MATRIX.md).
+4. Create pull request from [release preparation branch to main](https://github.com/eclipse-tractusx/item-relationship-service/compare/chore/prepare-release-x.x.x) and merge to main.
 5. Create Git tag for the desired release version `git tag x.x.x`
-   (the irs-helm tag will be created by the github workflow based on the version in the irs-helm changelog) 
-6. Push Git tag to repository `git push origin x.x.x`
-7. Wait for release workflow to complete
-8. Merge the automatically opened PR by github-actions bot
-9. Create pull request to eclipse-tractusx
-10. Notify about the release in IRS Matrix Chat. Template: 
+   (note: the irs-helm tag will be created automatically by the GitHub workflow based on the version in the irs-helm changelog). 
+6. Push Git tag to repository `git push origin x.x.x` (this will trigger the GitHub release workflow).
+7. Wait for release workflow to complete.
+8. Merge the automatically opened PR by GitHub actions bot.
+9. Notify about the release in IRS Matrix Chat using the following template: 
 
    >   **IRS Release x.x.x**
    >
@@ -177,7 +190,5 @@ https://github.com/google/google-java-format/blob/master/README.md#intellij-jre-
 
 ## Contact
 
-Contact the project developers via the project's "dev" list.
+See [CONTACT](CONTACT.md)
 
-* https://accounts.eclipse.org/mailing-list/tractusx-dev
-* Eclipse Matrix Chat https://chat.eclipse.org/#/room/#tractusx-irs:matrix.eclipse.org

FAQ.md

@@ -0,0 +1,113 @@
+
+[[Back to main IRS README](README.md)]
+
+
+# IRS FAQ
+
+
+## Documentation and Getting Help
+
+-----
+**Q: Where do I find documentation that helps me understand the big picture?**
+
+A: The following resources will help to understand the big picture:
+- [README - Introduction](README.md#introduction)
+- [More information describing the big picture](https://eclipse-tractusx.github.io/docs-kits/kits/Data%20Chain%20Kit/Adoption%20View%20Data%20Chain%20Kit/) 
+  including the two main flows IRS Iterative and IRS Recursive and involved components and services.
+
+Further information can be found in the IRS Architecture Documentation, for example:
+- [Architecture Documentation - Business Context](https://eclipse-tractusx.github.io/item-relationship-service/docs/arc42/full.html#_business_context)
+- [Architecture Documentation - Structure](https://eclipse-tractusx.github.io/item-relationship-service/docs/arc42/full.html#_structure)
+- [Architecture Documentation - Building block view](https://eclipse-tractusx.github.io/item-relationship-service/docs/arc42/full.html#_building_block_view)
+- [Architecture Documentation - Runtime view](https://eclipse-tractusx.github.io/item-relationship-service/docs/arc42/full.html#_runtime_view)
+    -  [Iterative Flow](https://eclipse-tractusx.github.io/item-relationship-service/docs/arc42/full.html#_irs_iterative)
+    -  [Recursive Flow](https://eclipse-tractusx.github.io/item-relationship-service/docs/arc42/full.html#_irs_recursive) 
+
+
+-----
+**Q: Where do I find the main documentation?**
+
+A: See [Item Relationship Service Documentation](https://eclipse-tractusx.github.io/item-relationship-service/docs/).
+
+
+-----
+**Q: Is there a glossary?**
+
+A: Yes, see [Item Relationship Service Documentation](https://eclipse-tractusx.github.io/item-relationship-service/docs/arc42/full.html#_glossary).
+
+
+-----
+**Q: Where do I get help?**
+
+A: Please read the documentation and tests first.
+If that does not answer your questions, ask the developers (see [CONTACT](CONTACT.md)).
+
+## Limitations, Bugs and Vulnerabilities
+
+-----
+**Q: Are there any known issues and limitation?**
+
+A: See [Known Issues and Limitations](README.md#known-issues-and-limitations).
+
+
+-----
+**Q: Where can I report a vulnerability?**
+
+A: See [SECURITY](SECURITY.md#reporting-a-vulnerability).
+
+
+-----
+**Q: Where can I report a bug?**
+
+A: Normal bugs may be reported as [public github issues](https://github.com/orgs/eclipse-tractusx/projects/8/views/10). 
+For reporting vulnerabilities see [SECURITY](SECURITY.md#reporting-a-vulnerability) please.
+
+
+## Usage
+
+-----
+**Q: Where do I find information concerning compatibility of dependencies?**
+
+A: See [COMPATIBILITY-MATRIX](COMPATIBILITY_MATRIX.md).
+
+## Contributing
+
+-----
+**Q: How can I contribute?**
+
+A: See [CONTRIBUTING](CONTRIBUTING.md).
+
+
+-----
+**Q: How do I create a release?**
+
+A: See [CONTRIBUTING](CONTRIBUTING.md#create-a-release).
+
+
+-----
+**Q: How do I format the code?**
+
+A: See [CONTRIBUTING](CONTRIBUTING.md#code-formatting).
+
+
+## Testing
+
+-----
+**Q: Where can I find more information concerning the type of tests and used technologies and libraries?**
+
+A: See [README - Tests](README.md#tests).
+
+-----
+**Q: Where do I find test data?**
+
+A: Testdata is located under [local/testing/testdata](local/testing/testdata). 
+For more information see the [test data README](local/testing/testdata/README.md).
+
+
+## Monitoring
+
+-----
+**Q: Where do I find information concerning monitoring?**
+
+See [README - Monitoring](README.md#monitoring).
+

INSTALL.md

@@ -62,4 +62,8 @@ A detailed instruction on how to configure the IRS and EDC can be found here: [A
 IRS provides a local setup which can be deployed to kubernetes.
 This setup includes all third-party services which IRS uses and interacts with.
 
-Instructions can be found here [README.md](README.md).
+Instructions can be found here [README](README.md).
+
+## Sample Calls
+
+Sample calls can be found here [USAGE](USAGE.md).