Fork A.B.C #38

ununhexium · 2025-04-22T12:53:41Z

New Fork

This procedure details how to fork a new version of the core EDC and migrate the changes of the previous version to that new version.

This procedure was updated for the last time for the 0.7.2 fork.
Keep in mind that any new EDC version comes with novelties and that this procedure may need adjustments.

Work Breakdown

As a general rule, look at the early diffs of the previous forks to see what was added of removed.

In this procedure, we will work with the following repositories

part ⬇ source ➡	Eclipse EDC (upstream)	sovity (fork)
core-edc	https://github.com/eclipse-edc/Connector	https://github.com/sovity/core-edc
actions	https://github.com/eclipse-edc/.github	https://github.com/sovity/core-edc-github
gradle plugin	https://github.com/eclipse-edc/GradlePlugins

Bonus

Helpful git commands.

Find the common ancestor

For instance to know from which commit on the main branch a pinned version comes from.

git merge-base A B finds the last common commit between the references A and B.

gitGraph
    commit
    commit id: "merge-base(A,B)" tag: "base"
    branch foo
    commit
    commit tag: "B"
    commit
    checkout main
    commit
    commit tag: "A"
    commit

Show a colored simplified graph

This will hide all the intermediate commits and show only the one that are key to understand the repo's tree structure: tags, branches with author, date, hash.

git log --graph --simplify-by-decoration --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all

Interactive git

https://jonas.github.io/tig/

Configuration

This procedure uses templates for the version.
It is advised to replace all the template strings with the version that you want to migrate for more clarity

Identify the versions that you migrate
NEXT is the upstream version that you want to fork from. e.g 0.7.2
- N1 is 0
- N2 is 7
- N3 is 2
PREVIOUS is the version that you will copy the fork changes from. e.g. 0.2.1.4
- P1 is 0
- P2 is 2
- P3 is 1
- P4 is 4
Replace the placeholders with the correct numbers
- sed --in-place 's/N1/0/g; s/N2/7/g; s/N3/2/g; s/P1/0/g; s/P2/2/g; s/P3/1/g; s/P4/4/g' fork.md

Let's fork!

Set up

Each version that needs forking has its own branch in the sovity fork.

Here we have an old fork that we want to get the features from named vP1.P2.P3.x and a new fork named vN1.N2.N3.x into which we want to port the changes made in vP1.P2.P3.x up to vP1.P2.P3.P4

Note: the branch names here are to be seen as references, so they should really be remotes/....

---
title: core-edc
---
%%{init: { 'logLevel': 'debug', 'gitGraph': {'mainBranchName': 'upstream/main' }} }%%
gitGraph
    commit tag: "v0.0.1"
    commit tag: "vP1.P2.0"
    branch upstream/bugfix/P1.P2.P3
    checkout upstream/bugfix/P1.P2.P3
    commit
    commit tag: "vP1.P2.P3"
    branch fork/sovity/P1.P2.P3
    commit
    commit
    commit tag: "vP1.P2.P3.P4"
    checkout upstream/bugfix/P1.P2.P3
    checkout upstream/main
    commit
    commit
    commit tag: "vN1.N2.0"
    branch upstream/bugfix/N1.N2.N3
    checkout upstream/bugfix/N1.N2.N3
    commit tag: "vN1.N2.1"
    commit tag: "vN1.N2.2"
    commit tag: "vN1.N2.N3" id: "to fork"
    branch fork/sovity/N1.N2.N3
    commit id: "new fork"
    commit tag: "vN1.N2.N3.1"
    checkout upstream/main
    commit
    commit

Important

Note: the upstream branch name may vary:

remotes/upstream/release/0.10.0
remotes/upstream/bugfix/0.7.2
remotes/upstream/v0.6.5
or just nothing, then use the tag to start a branch.

Make it work locally

This section describes the steps to prepare the fork and make it run locally.

Setup a repository

Clone the fork core-edc
- git clone --origin fork [email protected]:sovity/core-edc.git
Add the upstream repository
- git remote add upstream [email protected]:eclipse-edc/Connector.git
Fetch the upstream tags
- git fetch --all --tags

Setup example

Your repository now looks like this:

git remote -v

fork	[email protected]:sovity/core-edc.git (fetch)
fork	[email protected]:sovity/core-edc.git (push)
upstream	[email protected]:eclipse-edc/Connector.git (fetch)
upstream	[email protected]:eclipse-edc/Connector.git (push)

git branch -a

# ... are comments to describe the situation and no part of the output.

remotes/fork/default               # the replacement for upstream/main use in the sovity fork
remotes/fork/main                  # not used in the fork, deplaced by main
remotes/fork/sovity/O12.O3         # the previous fork branch
remotes/upstream/bugfix/N1.N2.N3   # the branch we want to work
... more                           # and many other branches

git tag -l

The output will vary based on the version that have already been forked. Here is the output where 0.2.1 exists and 0.7.2 will be forked.

# ... are comments to describe the situation and no part of the output.

v0.2.1    # the upstream previously forked version
v0.2.1.2  # v0.2.1.1 is missing because it was never published correctly and was replaced by 0.2.1.2
v0.2.1.3
v0.2.1.4  # the latest sovity fork version of v0.2.1
v0.7.2    # the version we want to fork
... more

Establish the branches

In the fork, find the tag vN1.N2.N3 of the branch that you want to fork from.
Create a new branch sovity/N1.N2.N3 from that tag.
- git checkout -b sovity/N1.N2.N3 vN1.N2.N3
Push this branch to the fork. It will be our new main for this fork version.
- git push fork sovity/N1.N2.N3:sovity/N1.N2.N3
Checkout a new branch N1.N2.N3-fork-setup on the same commit as sovity/N1.N2.N3.x.
- git checkout sovity/N1.N2.N3
- git checkout -b N1.N2.N3-fork-setup
In gradle.properties, set the correct branch version: N1.N2.N3.1.

git remote show fork

* remote fork
  Fetch URL: [email protected]:sovity/core-edc.git
  Push  URL: [email protected]:sovity/core-edc.git
  HEAD branch: doesntMatter
  Remote branches:
    sovity/P1.P2.P3        tracked
    sovity/N1.N2.N3         tracked
    ... more
  Local branches configured for 'git pull':
    sovity/N1.N2.N3 merges with remote sovity/N1.N2.N3
    ... more
  Local refs configured for 'git push':
    sovity/N1.N2.N3 pushes to sovity/N1.N2.N3 (up to date)
    ... more

Update the project

Make it work in the CI

Find the correct GitHub action.

The EDC, as of 0.7.x, uses actions that are located in a separate repository. That repository is forked.

Because the EDC used the @main version in its CI, it is certain that the scripts that are the current @main ones were not the ones that were originally used for the Eclipse EDC release you're forking, and it is likely that the current scripts will fail, be renamed, have a different behaviour, ...

In a best-effort attempt to restore the CI, we need to pin the versions that were used and maybe update them to work on the current GitHub.

If we pin down the old version, a lot of updates may be needed.

If we pin down the new version, scripts may be missing.

The strategy here is to pin down the latest from main and fix the missing scripts individually and later update them.

Set up a repository

Clone the fork actions repository
- git clone --origin fork [email protected]:sovity/core-edc-github.git
Add the upstream actions repository
- git remote add upstream [email protected]:eclipse-edc/.github.git
Update
- git fetch --all --tags

Result

git remote -v

fork	[email protected]:sovity/core-edc-github.git (fetch)
fork	[email protected]:sovity/core-edc-github.git (push)
upstream	[email protected]:eclipse-edc/.github.git (fetch)
upstream	[email protected]:eclipse-edc/.github.git (push)

Overview

Here is the example forking scenario.

---
title: actions
---
%%{init: { 'logLevel': 'debug', 'gitGraph': {'mainBranchName': 'upstream/main' }} }%%
gitGraph
    commit id: "obsolete"
    commit
    commit id: "core-edc fork tag date" tag: "N1.N2.N3_LASTOK_1"
    branch fork/pinned/N1.N2.N3_LASTOK
    commit tag: "N1.N2.N3_LASTOK_2"
    commit tag: "N1.N2.N3_LASTOK_3"
    checkout upstream/main
    commit
    commit
    commit
    commit id: "latest" tag: "N1.N2.N3_LATEST_1"
    branch fork/pinned/N1.N2.N3_LATEST
    commit tag: "N1.N2.N3_LATEST_2"
    commit tag: "N1.N2.N3_LATEST_3"

LATEST and LASTOK are iso dates YYYY-MM-DD

The naming scheme for the tagged and updated actions is fork version _ date at which the action was working _ -version

e.g. N1.N2.N3_2025-06-07_1 for the latest main commit.
e.g. N1.N2.N3_2022.03.04_3 for the commit that was used during releasing, 3rd revision. Here the _3 is related to the actions fork scripts and is independent of the 4th digit in the core-edc fork.
You will need potentially many revisions as you will need to push the tag each time you make a change to let the CI use that version, then retry if it failed.

This was tested to work quite well in version 0.7.2 and is detail below.

For the cases that can't be covered with the best effort approach, a fork strategy is detailed below,
see Lost action

If you need more than 1 branch for a single date, be creative in the name, either use DATE+TIME or DATE+suffix. In any case, that scenario is unlikely to happen.

Finding LATEST and LASTOK

LATEST is the last commit on the main upstream branch.

Replace LATEST in this file by the date you find. The date part should be enough.
git show --no-patch --format=%ci upstream/main
sed --in-place 's/LATEST/2025-06-07/g' fork.md

LASTOK is optional and will be defined later.

Pin the action versions

Pin the latest version
- Create a branch to track the LATEST main commit from upstream
  - git checkout upstream/main
  - git checkout -b pinned/N1.N2.N3_LATEST
- Push the branch to the fork
  - git push fork
- Tag the latest commit in the action set with the label core edc fork branch _ today _ 1
  - git tag N1.N2.N3_LATEST_1 pinned/N1.N2.N3_LATEST
- Push that new tag to the sovity core edc github fork
  - git push fork tag N1.N2.N3_LATEST_1
- Change all the action's @main version for the N1.N2.N3_LATEST_1 version
- Change all the eclipse-edc/.github for sovity/core-edc-github
  - ❌ eclipse-edc/.github/.github/workflows/task.yml@main
  - ✔ sovity/core-edc-github/.github/workflows/[email protected]_LATEST_1
  - IDE: replace eclipse-edc/.github/(.*)@main with sovity/core-edc-github/[email protected]_LATEST_1
- Run the CI via a PR and check for errors

From here we have:

An action works -> done
An action doesn't work
- Is the action useless? -> remove it
  - Discord webhook
  - First interaction
  - Others...
  - Disable failing tests that don't matter
    - failing because of outdated certificates
- An action has an obsolete dependency / needs adjustments -> see Adjust the pinned main
- An action is missing: we need to find it in the history -> see Lost action
- Something else that was not encountered yet: be creative and update this guide after you found the solution.

Adjust the pinned main

Update the code in the pinned/N1.N2.N3-LATEST branch
Commit and tag your new version as N1.N2.N3_LATEST_(N+1) in the actions repo
Push the tag to the sovity fork repo
Update all the @N1.N2.N3_LATEST_N to N1.N2.N3_LATEST_(N+1)
Repeat until fixed

Lost action

This part describes how to find where a missing action was and how to make it work again.

Publishing

Finalization

Update this procedure with new hints after forking an EDC version.
Update the default branch's README with a new entry for this fork.

The text was updated successfully, but these errors were encountered:

ununhexium mentioned this issue Apr 23, 2025

0.11.1 fork setup #39

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fork A.B.C #38

Fork A.B.C #38

ununhexium commented Apr 22, 2025 •

edited

Loading

Fork A.B.C #38

Fork A.B.C #38

Comments

ununhexium commented Apr 22, 2025 • edited Loading

New Fork

Work Breakdown

Steps

Bonus

Find the common ancestor

Show a colored simplified graph

Interactive git

Configuration

Let's fork!

Set up

Make it work locally

Setup a repository

Setup example

Establish the branches

Update the project

Make it work in the CI

Find the correct GitHub action.

Set up a repository

Result

Overview

Finding LATEST and LASTOK

Pin the action versions

Adjust the pinned main

Lost action

Publishing

Finalization

ununhexium commented Apr 22, 2025 •

edited

Loading