Merge pull request #319 from borisrizov-zf/feature/update-contributio…

…n-docs

chore: add contribution docs and committer docs

CONTRIBUTING.md

@@ -44,6 +44,79 @@ The project maintains the source code repositories in the following GitHub organ
 
 * https://github.com/eclipse-tractusx/
 
+### How to submit pull requests
+
+It is paramount to ensure that the git history of the project remains clean and
+consistent. This means that the usage of concise and expressive commits **MUST**
+be used. Other helpful tips are to always rebase your branch before submitting
+the pull request.
+
+First make sure you are working on your fork of the project, for example:
+
+```shell
+$ git remote show origin
+* remote origin
+Fetch URL: git@github.com:borisrizov-zf/managed-identity-wallet.git
+Push  URL: git@github.com:borisrizov-zf/managed-identity-wallet.git
+```
+
+Make sure you setup a remote which points at the Tractus-X repository:
+
+```shell
+git remote add upstream git@github.com:eclipse-tractusx/managed-identity-wallet.git
+```
+
+Whenever you want to start working, pull all changes from your remotes:
+
+```shell
+git fetch --all
+```
+
+Then rebase your develop branch:
+
+```shell
+git checkout develop
+git rebase upstream/develop
+```
+
+At this point your branches are synced and you can create a new branch:
+
+```shell
+git checkout -b feature/add-some-feature
+```
+
+### For Eclipse Committers and Maintainers
+
+The project uses the tool `semantic-release` to automatically create releases
+and manage CHANGELOG.md entries. These files **SHOULD** never be manually edited
+nor present in any PR. If you see this file in a PR, it means the incoming branch
+is not at the tip of the project history - it will most likely mangle your project
+when merged.
+
+You'll find all important steps in the files `.github/release.yaml` and `.releaserc`.
+
+The development work is always done on branch `develop`, all pull requests are made
+against `develop`. When it is time to create an official release a PR from `develop`
+to `main` must be created. **IMPORTANT**: after merging, you **MUST** wait for the
+pipeline to complete, as it will create two new commits on `main`. After that you
+**MUST** create a PR, merging main back into develop, to obtain these two new commits,
+and to kick-off the new tag on `develop`. Failing to do so will result in a huge
+headache, spaghetti code, faulty commits and other "life-improving" moments. **DO NOT
+MESS THIS STEP UP**.
+
+It is possible to test how a release will work on your own fork, **BUT** you'll have
+to do some extra work to make it happen. `semantic-release` uses git notes to track
+the tags. You'll have to sync them manually (as most git configs do not include the settings
+to do so automatically):
+
+```shell
+git fetch upstream refs/notes/*:refs/notes/*
+git push origin --tags
+git push origin refs/notes/*:refs/notes/*
+```
+
+At this point your repository will behave exactly like upstream when doing a release.
+
 ## Eclipse Development Process
 
 This Eclipse Foundation open project is governed by the Eclipse Foundation

README.md

@@ -6,6 +6,40 @@ The Managed Identity Wallets (MIW) service implements the Self-Sovereign-Identit
 
 See [INSTALL.md](INSTALL.md)
 
+# Committer Documentation
+
+*(This section is also intentionally included in the CONTRIBUTING.md file)*
+
+The project uses the tool `semantic-release` to automatically create releases
+and manage CHANGELOG.md entries. These files **SHOULD** never be manually edited
+nor present in any PR. If you see this file in a PR, it means the incoming branch
+is not at the tip of the project history - it will most likely mangle your project
+when merged.
+
+You'll find all important steps in the files `.github/release.yaml` and `.releaserc`.
+
+The development work is always done on branch `develop`, all pull requests are made
+against `develop`. When it is time to create an official release a PR from `develop`
+to `main` must be created. **IMPORTANT**: after merging, you **MUST** wait for the
+pipeline to complete, as it will create two new commits on `main`. After that you
+**MUST** create a PR, merging main back into develop, to obtain these two new commits,
+and to kick-off the new tag on `develop`. Failing to do so will result in a huge
+headache, spaghetti code, faulty commits and other "life-improving" moments. **DO NOT
+MESS THIS STEP UP**.
+
+It is possible to test how a release will work on your own fork, **BUT** you'll have
+to do some extra work to make it happen. `semantic-release` uses git notes to track
+the tags. You'll have to sync them manually (as most git configs do not include the settings
+to do so automatically):
+
+```shell
+git fetch upstream refs/notes/*:refs/notes/*
+git push origin --tags
+git push origin refs/notes/*:refs/notes/*
+```
+
+At this point your repository will behave exactly like upstream when doing a release.
+
 # Developer Documentation
 
 To run MIW locally, this section describes the tooling as well as the local development setup.