Present Changes needed before Publication of the Repo (admin-shell-io…

…#108)

* prepare contribution guide and add more issue templates
* correcting outdated statements in the README and adding descriptions on the releases

.github/ISSUE_TEMPLATE/issue-template-for-bugs.md

@@ -0,0 +1,24 @@
+---
+name: Issue Template for Bug Reports
+about: Describe this issue's purpose here.
+title: '[BUG] Replace Title'
+labels: 'bug'
+assignees: ''
+
+---
+
+# What happens?
+
+*Describe the problem in short sentences, add a minimal example if possible*  
+...
+
+# Why is this wrong?
+
+*Describe why this is a problem.* 
+
+# How should it be fixed?
+
+*Describe which change will fix the problem.* 
+...
+
+- [ ] I have signed the required Developer Certificate of Origin ([DCO](https://developercertificate.org)) already.

.github/ISSUE_TEMPLATE/issue-template-for-feature-requests.md

@@ -0,0 +1,22 @@
+---
+name: Issue Template for Requesting new AAS API Features
+about: Describe this issue's purpose here.
+title: '[Feat. Req.] Replace Title'
+labels: 'enhancement'
+assignees: ''
+
+---
+
+# What is missing?
+
+*Describe the problem in short sentences, add a minimal example if possible*  
+...
+
+
+# How should it be fixed?
+
+*Describe which change will fix the problem.* 
+...
+
+
+- [ ] I have signed the required Developer Certificate of Origin ([DCO](https://developercertificate.org)) already.

.github/ISSUE_TEMPLATE/issue-template-for-review-findings.md

@@ -16,3 +16,6 @@ assignees: ''
 ...
 
 This issue relates to finding `XX#??`.
+
+
+- [ ] I have signed the required Developer Certificate of Origin ([DCO](https://developercertificate.org)) already.

CONTRIBUTING.md

@@ -1,31 +1,51 @@
 # Contributing
 
-The specification of [Asset Administration Shell - Part 2] is an official publication of the joint working group "Asset Administration Shell" of the [Platform Industrie 4.0] and [IDTA].
-The specification and the API descriptions must be particularly compliant with this.
-However, we highly invite the community to review, report and fix the definitions. 
-To keep the management effort under control, we demand a defined procedure for the contribution in this repository.
+The [Specification of the Asset Administration Shell - Part 2] is an official publication of the [IDTA] work stream "AAS in Detail".
+The API definitions in this repository must be particularly compliant with this specification.
+To ensure a faster adoption and improvement of AAS API, we invite the community to contribute with reviews, reporting issues, and fixing them.  
+Do you want to contribute? Great! But before you do it, please follow the defined procedure for the contribution in this repository. 
+
+[Specification of the Asset Administration Shell - Part 2]: https://industrialdigitaltwin.org/en/content-hub/
+
+
+## Prerequisites
+
+**Please note** that by submitting an Issue or a Pull Request (PR), you aggree that the created content falls under a Developer Certificate of Origin ([DCO]), by which you declare that you have the legal right to contribute the content under the stated license and that the [IDTA] and the maintainers of this repository are allowed to use your contribution for publications, e.g., [Specification of the Asset Administration Shell - Part 2]. In certain cases, an additional signing of a Contributor License Agreement (CLA) can be required. It is up to the maintainers of this repository to decide whether an individual contribution needs also a signed CLA. In case the contributor does not sign it in an appropriate time span after being notified, the contribution cannot be used further and in particular can not appear in any release.
+
+[DCO]: https://developercertificate.org 
+
+
+## Raising Issues
+
+[Github Issues](https://github.com/admin-shell-io/aas-specs-api/issues) are the preferred way to inform the community about bugs, shortcomings, feature requests and so on.  
+
+
+**Use a template**. Several issue templates are available to better structure the process. Depending on your issue, submit a review finding, a bug report, or a request for a new feature. Only if none of these fits, [open a new blank issue](https://github.com/admin-shell-io/aas-specs-api/issues/new). Due to legal reasons, click also the checkmark stating that you have already signed the [DCO] (see [Section Prerequisites](#prerequisites)).  
+A maintainer will then assign additional labels, milestones, and individual other contributers if possible.
 
-[Asset Administration Shell - Part 2]: https://www.plattform-i40.de/PI40/Redaktion/EN/Standardartikel/specification-administrationshell.html
 
 ## Before the Pull Requests
 
+If you are contributing for the first time, please inform yourself about the [LICENSE](./LICENSE.txt) used for this repository. Also, you will be asked to sign a [DCO] if not done already (see [Section Prerequisites](#prerequisites)). Different to issues, Pull Requests are checked automatically through the [CLA Assistant](https://cla-assistant.io).
+
+
 **Create Feature branches**.
 We develop using the feature branches, see [this section of the Git book].
 
 [this section of the Git book]: https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows.
 
-If you are a member of the development team, [create a feature branch] directly within the repository.
+If you are a member of the IDTA workstream team, [create a feature branch] directly within the repository.
 
 [create a feature branch]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository
 
-Otherwise, if you are a non-member contributor, fork the repository and create the feature branch in your forked repository. See [this Github tutorial] for more guidance.
-Please **do not** fork the SwaggerHub APIs and simply point to your updated API.
-SwaggerHub does not provide any difference view, increasing the manual effort unnecessarily.
+Otherwise, if you are a non-member contributor, fork the repository and create the feature branch in your forked repository. See [this Github tutorial] for more guidance. 
 
 [this Github tutorial]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork
 
+
+
 **Branch Prefix**.
-Please prefix the branch with your Github user name (*e.g.,* `sebbader/Add-some-feature`).
+Please prefix the branch with your Github user name (*e.g.,* `my-user/Add-some-feature`).
 
 ## Recommendation for Commit Messages
 
@@ -38,38 +58,52 @@ The commit messages follow the guidelines from https://chris.beams.io/posts/git-
 * Wrap the body at 72 characters
 * Use the body to explain *what* and *why* (instead of *how*)
 
-
 ## Create Pull Request
 After all changes have been committed to your feature branch, a [pull request] (PR) has to be created.
-Every PR should be linked to an issue for tracking.
+Every PR must be linked to an issue for tracking.
 See [this Github tutorial] for more guidance. 
 
 [pull request]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
 
 [link PR to issue]: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue
 
+The discussion on the issue's content happends in the issue and not the PR. The discussion in the PR should focus on the reviewer's remarks.
+
+## Pre-Merge Checks
+**Continuous Integration.**
+Github will run the continuous integration (CI) automatically through Github actions to verify that the submitted changes are valid.
+Every pull request automatically runs the continuous integration with every update.
+
+The continuous integration must be **successfully completed** with `All checks have passed` before proceeding with the approval process.
+
+
+### Check Commit and Pull Request Messages
+In accordance with Section "Recommendation for Commit Messages" the continuous integration checks the previously defined conditions.
+For the present development, however, this is not enforced.
 
 ## Approval Process
-All changes must be **reviewed** and **approved**.
+All changes must be **reviewed** and **approved** by members of the IDTA workstream "AAS in Detail".
 
-Minor changes (simple failures, typos, *etc.*) and additional content (more examples, etc.) can be accepted straight away after a brief review by the responsible reviewers.
+Minor changes (simple failures, typos, *etc.*) and additional content (more examples, etc.) can be accepted straight away after a brief review by at least one responsible reviewers.
 
-Major changes must first be reviewed and approved by the joint working group "Asset Administration Shell" of the [Platform Industrie 4.0] and [IDTA].
+Major changes must first be presented and approved in the [IDTA] workstream "AAS in Detail". If the creator of a PR is not a member of the workstream, a dedicated assignee will present it.
 
 [Platform Industrie 4.0]: http://www.plattform-i40.de
 [IDTA]: https://industrialdigitaltwin.org/
 
 
+## Merge into `main` Branch
 
-## Merge into Master Branch
+After the approval, the pull request can be merged into the repository. This is done by one of the maintainers.  
+Bugfixes might be collected together first and then be merged through one indivdual commit. Similarly, new features are first collected in defined minor/major release branches, and merged into the `main` at the time when the corresponding version of the specification is published.
 
-After the approval the pull request can be merged into the repository. This is done by one of the maintainers.
+*Note:* Changes into external resources, e.g. Swaggerhub, are done by the members of the IDTA workstream immediatly after the indivdual PRs have been merged. The leading source is always the content of this repository. 
 
 
 ## Post-Merge Cleanup
 **Congratulation.**
-You successfully contributed to the aas-spec repository.
+You successfully contributed to the aas-spec-api repository.
 
-If you are a member of the development team, please delete the feature branch you directly created within the aas-specs repository.
+If you are a member of the workstream team, please delete the feature branch you directly created within the aas-specs-api repository.
 
-Otherwise, if you are not part of the team and you forked the repository, feel free to delete your fork.
+Otherwise, if you are not part of the team and you forked the repository, feel free to delete your fork.

README.md

@@ -6,26 +6,29 @@ https://licensebuttons.net/l/by/4.0/88x31.png
 https://creativecommons.org/licenses/by/4.0/
 )
 
-This repository contains specifications of the Asset Administration Shell API, including in particular the normative OpenAPI files of the AAS REST API.
+This repository contains specifications of the Asset Administration Shell APIs, including in particular the normative OpenAPI files of the AAS HTTP/REST API.
 These API descriptions are derived from the document series, part 2,
-["Details of the Asset Administration Shell"](
-https://www.plattform-i40.de/PI40/Redaktion/EN/Standardartikel/specification-administrationshell.html
-) published by the [Platform Industrie 4.0](http://www.plattform-i40.de) and [IDTA](https://industrialdigitaltwin.org/en/).
+["Specification of the Asset Administration Shell - Part 2"](
+https://industrialdigitaltwin.org/en/content-hub/
+) published by the [IDTA](https://industrialdigitaltwin.org/en/).
 
 
 
 ## Content
 This repository provides the OpenAPI files published in the SwaggerHub organization [Plattform_i40](https://app.swaggerhub.com/search?owner=Plattform_i40).
 All published SwaggerHub APIs are synchronized all the time with the respective folders in this repository using the [GitHub Integration](https://support.smartbear.com/swaggerhub/docs/integrations/github-sync.html) feature. In particular, the following APIs are contained:
-* [Entire-API-Collection/openapi.yaml](./Entire-API-Collection/openapi.yaml) matches the [Entire-API-Collection API at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/Entire-API-Collection)
-* [AssetAdministrationShell-Environment/openapi.yaml](./AssetAdministrationShell-Environment/openapi.yaml) matches the [AssetAdministrationShell-Environment API at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShell-Environment)
-* [AssetAdministrationShell-API/openapi.yaml](./AssetAdministrationShell-API/openapi.yaml) matches the [AssetAdministrationShell API at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShell-API)
-* [Submodel-API/openapi.yaml](./Submodel-API/openapi.yaml) matches the [Submodel API at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/Submodel-API)
+* [AssetAdministrationShellServiceSpecification](./AssetAdministrationShellServiceSpecification) matches the [Asset Administration Shell Service Specification at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellServiceSpecification) and contains all its profiles
+* [AssetAdministrationShellRepositoryServiceSpecification](./AssetAdministrationShellRepositoryServiceSpecification) matches the [Asset Administration Shell Repository Service Specification at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRepositoryServiceSpecification) and contains all its profiles
+* [SubmodelServiceSpecification](./SubmodelServiceSpecification) matches the [Submodel Service Specification at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/SubmodelServiceSpecification) and contains all its profiles
+* [SubmodelRepositoryServiceSpecification](./SubmodelRepositoryServiceSpecification) matches the [Submodel Repository Service Specification at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRepositoryServiceSpecification) and contains all its profiles
+* [AssetAdministrationShellRegistryServiceSpecification](./AssetAdministrationShellRegistryServiceSpecification) matches the [Asset Administration Shell Registry Service Specification at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification) and contains all its profiles
+* [SubmodelRegistryServiceSpecification](./SubmodelRegistryServiceSpecification) matches the [Submodel Registry Service Specification at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRegistryServiceSpecification) and contains all its profiles
 * [AASX-File-Server/openapi.yaml](./AASX-File-Server/openapi.yaml) matches the [AASX-File-Server API at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/AASX-File-Server)
-* [Registry-and-Discovery/openapi.yaml](./Registry-and-Discovery/openapi.yaml) matches the [Registry-and-Discovery API at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/Registry-and-Discovery)
+* [DiscoveryServiceDescription](./DiscoveryServiceDescription) matches the [Discovery Service Description API at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/DiscoveryServiceDescription)
+* [Entire-API-Collection/openapi.yaml](./Entire-API-Collection/openapi.yaml) matches the [Entire-API-Collection API at SwaggerHub](https://app.swaggerhub.com/apis/Plattform_i40/Entire-API-Collection)
 
 The following *domains* are synchronized manually as domain synchronization is not yet available in SwaggerHub:
-* [Part1-MetaModel-Schemas/openapi.yaml](./art1-MetaModel-Schemas/openapi.yaml) matches the [Part1-MetaModel-Schemas Domain at SwaggerHub](https://app.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas)
+* [Part1-MetaModel-Schemas/openapi.yaml](./Part1-MetaModel-Schemas/openapi.yaml) matches the [Part1-MetaModel-Schemas Domain at SwaggerHub](https://app.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas)
 * [Part2-API-Schemas/openapi.yaml](./Part2-API-Schemas/openapi.yaml) matches the [Part2-API-Schemas Domain at SwaggerHub](https://app.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas)
 * [DINSPEC16593-Schemas/openapi.yaml](./DINSPEC16593-Schemas/openapi.yaml) matches the [DINSPEC16593-Schemas Domain at SwaggerHub](https://app.swaggerhub.com/domains/Plattform_i40/DINSPEC16593-Schemas)
 
@@ -34,14 +37,26 @@ The following *domains* are synchronized manually as domain synchronization is n
 ## API Versions in GitHub Branches
 
 The `main` branch contains the latest released version of all APIs and Domains. Current and previously released states are tagged with the corresponding release version in this repository, and marked with the `Published` tag in SwaggerHub.
-Working versions may be marked as `private` in SwaggerHub and therfore may not be visible to the public audience yet. In this repository, working versions appear as branches named after the target release version. Note: In order to synchronize with the same GitHub branch, all versions should follow the exact same pattern.
+Working versions may be marked as `private` in SwaggerHub and therfore may not be visible to the public audience yet. In this repository, working versions appear as branches named after the target release version.  
+**Note:** In order to synchronize with the same GitHub branch, all versions should follow the exact same pattern.
+
+### Releases
+
+The following versioning scheme is applied for release tags: 'V\<major>.\<minor>.\<patch>'. 
+Major versions indicate breaking changes while minor updates are backward compatible.
+The patch position is increased whenever bugfixes need to be applied. 
+The following release contains the latest version of the AAS schemas (see also the [releases](https://github.com/admin-shell-io/aas-specs-api/releases) section of this repository):
+* [3.0.1](https://github.com/admin-shell-io/aas-specs/releases/tag/V3.0.1) is the corresponding release for the `V3.0.1` version of the AAS APIs, containing the normative schemas for the published document "Specification of the Asset Administration Shell - Part 2: Application Programming Interfaces - **Version 3.0.1**". *Use this release if you want to work with the latest specified AAS version.*
+
+Previous releases (deprecated by [3.0.1](https://github.com/admin-shell-io/aas-specs/releases/tag/V3.0.1)):
+* [3.0](https://github.com/admin-shell-io/aas-specs/releases/tag/V3.0) is the first major release for the AAS APIs, containing the normative API descriptions for the published document "Specification of the Asset Administration Shell - Part 2: Application Programming Interfaces - Version 3.0".
 
 
 ## Contributing
 
 Feature requests, reports about inconsistencies, mistakes *etc.* are highly
 welcome! Please [submit a new issue](
-https://github.com/admin-shell-io/aas-specs-api/issues/new
+https://github.com/admin-shell-io/aas-specs-api/issues/new/choose
 ).
 
 If you want to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -50,4 +65,4 @@ If you want to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## SwaggerHub GitHub Synchronization
 
-SwaggerHub requires a GitHub Access Token with `repo` permissions. It is good practice that the selected token has a defined expiration date. Therefore, at some point in the future when the current token expires, the synchronization will fail and a new token needs to be added through the IDTA repository management team.
+SwaggerHub requires a GitHub Access Token with `repo` permissions. It is good practice that the selected token has a defined expiration date. Therefore, at some point in time when the current token expires, the synchronization will fail and a new token needs to be added through the IDTA repository management team.