From 8e74e76c424fa975c75fa63ca0a78ba705fc18b2 Mon Sep 17 00:00:00 2001 From: Boris Rizov Date: Tue, 18 Jun 2024 10:05:39 +0200 Subject: [PATCH] chore: add contribution docs and committer docs --- CONTRIBUTING.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 34 +++++++++++++++++++++++ 2 files changed, 107 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e702f38e..9246e1b5 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index df4bdf8c..a4c2920d 100644 --- a/README.md +++ b/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.