From 7826ec30d12908c44765d9f3703a2f6a6d340e5d Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger Date: Mon, 3 Apr 2023 10:32:58 +0200 Subject: [PATCH 1/3] docs: create decision record about renaming git branches --- .../2023-04-03_renaming_branches/README.md | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 docs/development/decision-records/2023-04-03_renaming_branches/README.md diff --git a/docs/development/decision-records/2023-04-03_renaming_branches/README.md b/docs/development/decision-records/2023-04-03_renaming_branches/README.md new file mode 100644 index 000000000..dcb80865c --- /dev/null +++ b/docs/development/decision-records/2023-04-03_renaming_branches/README.md @@ -0,0 +1,61 @@ +# Renaming Git branches to comply with TractusX standards + +## Decision + +TractusX-EDC will rename its Git branching structure to comply with TractusX release guidelines, and to be able to +leverage +GitHub convenience features, while continuing to use the Gitflow branching model. + +## Rationale + +The TractusX organization has established +a [release guideline](https://eclipse-tractusx.github.io/docs/release/trg-2/trg-2-1/) which mandates that all projects' +default branch be called `main`. + +### Selecting default branches + +In GitHub, the default branch has a couple of important features attached to it: + +- cloning or forking the repository will automatically check out the default branch +- when creating pull requests the default branch is targeted by default +- [automatic issue linking and closing](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) + only works with the default branch + +### The problem with GitFlow + +The GitFlow branching model suggests that the day-to-day work be done on a branch called `develop`, while the `main` +branch stores the version history and only receives (merge) commits after a version releases. + +This would call for `develop` being the GitHub default branch, which is forbidden by the aforementioned release +guideline. + +## Approach + +In order to comply with the TractusX release guideline, to make use of the GitHub features _and_ also use GitFlow, we +propose renaming a couple of branches. While GitFlow _suggests_ branch names, it does not _require_ it, and most +tools allow for customizing them anyway. Thus, from an abstract perspective, the following changes are necessary: + +- `main` becomes our work/development branch. All pull requests target `main`. +- `develop` gets deleted +- a new branch `releases` is introduced, which tracks the release history and receives post-release merge commits. + +Technically this will involve force-pushing, which is a potentially destructive operation. Therefor the following +section outlines the exact sequence of steps. Note that "upstream" refers to `eclipse-tractusx/tractusx-edc`, while " +fork" refers to `catenax-ng/tx-tractusx-edc`. + +- create a new branch `upstream/releases` +- create a new branch `fork/releaes`, set it to track `upstream/releases` +- push the contents of `fork/main` -> `upstream/releases` +- synchronize `upstream/develop` with `fork/develop` +- force-push the contents of `develop` -> `upstream/main` (do **not** update the tracking branch!) +- synchronize `upstream/main` -> `fork/main`. +- delete/archive `upstream/develop` and `fork/develop` + +_Note that most of this will likely need to be done manually, since GitHub does not allow for advanced Git operations +like force-pushing. Write access to `upstream` is required!_ + +## Further notes + +The new `releases` branch (note the plural) will serve the same purpose that `main` did up until now, which is to track +all releases (via merge commits and tags) in chronological order. We will continue to have separate `release/x.y.z` +branches for every release. \ No newline at end of file From a16313f8f301ee7979787abd3bb1e8b9a4e3deef Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger <43503240+paullatzelsperger@users.noreply.github.com> Date: Tue, 4 Apr 2023 09:51:50 +0200 Subject: [PATCH 2/3] Update docs/development/decision-records/2023-04-03_renaming_branches/README.md Co-authored-by: Florian Rusch (ZF Friedrichshafen AG) --- .../decision-records/2023-04-03_renaming_branches/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/decision-records/2023-04-03_renaming_branches/README.md b/docs/development/decision-records/2023-04-03_renaming_branches/README.md index dcb80865c..5fc2fe4e5 100644 --- a/docs/development/decision-records/2023-04-03_renaming_branches/README.md +++ b/docs/development/decision-records/2023-04-03_renaming_branches/README.md @@ -48,7 +48,7 @@ fork" refers to `catenax-ng/tx-tractusx-edc`. - push the contents of `fork/main` -> `upstream/releases` - synchronize `upstream/develop` with `fork/develop` - force-push the contents of `develop` -> `upstream/main` (do **not** update the tracking branch!) -- synchronize `upstream/main` -> `fork/main`. +- synchronize `upstream/main` -> `fork/main` - delete/archive `upstream/develop` and `fork/develop` _Note that most of this will likely need to be done manually, since GitHub does not allow for advanced Git operations From 4b4b0456c890300e9a10c4f0f636db30e9957df0 Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger <43503240+paullatzelsperger@users.noreply.github.com> Date: Tue, 4 Apr 2023 09:51:57 +0200 Subject: [PATCH 3/3] Update docs/development/decision-records/2023-04-03_renaming_branches/README.md Co-authored-by: Florian Rusch (ZF Friedrichshafen AG) --- .../decision-records/2023-04-03_renaming_branches/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/decision-records/2023-04-03_renaming_branches/README.md b/docs/development/decision-records/2023-04-03_renaming_branches/README.md index 5fc2fe4e5..7bc3abd64 100644 --- a/docs/development/decision-records/2023-04-03_renaming_branches/README.md +++ b/docs/development/decision-records/2023-04-03_renaming_branches/README.md @@ -44,7 +44,7 @@ section outlines the exact sequence of steps. Note that "upstream" refers to `ec fork" refers to `catenax-ng/tx-tractusx-edc`. - create a new branch `upstream/releases` -- create a new branch `fork/releaes`, set it to track `upstream/releases` +- create a new branch `fork/releases`, set it to track `upstream/releases` - push the contents of `fork/main` -> `upstream/releases` - synchronize `upstream/develop` with `fork/develop` - force-push the contents of `develop` -> `upstream/main` (do **not** update the tracking branch!)