You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.11.1 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 or removed.
In this procedure, we will work with the following repositories
Helpful git commands. Just a few tips about the commands that could help. AI can probably help too. It will be mentioned later when these will be useful.
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.
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.
Auto-merging CHANGELOG.md
CONFLICT (content): Merge conflict in CHANGELOG.md
Auto-merging docs/developer/fork/0.7.2.X.md
error: could not apply fcb9c94c9... fix: Remove file separator to access classpath (#27)
hint: After resolving the conflicts, mark them with
hint: "git add/rm <pathspec>", then run
hint: "git cherry-pick --continue".
hint: You can instead skip this commit with "git cherry-pick --skip".
hint: To abort and get back to the state before "git cherry-pick",
hint: run "git cherry-pick --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Alternatively, you may try a diff+apply+merge between the commits of the previous fork may be enough to port the change git apply <(git diff vP1.P2... vP1.P2...).
Fix the picking conflict
Open the merge diff in your prefered tool
git mergetool
Preview older revision
See what a folder looked like without checking it out
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.11.1. It is made of 3 parts following parts:
0 is 0
N2 is 11
N3 is 1
PREVIOUS is the version that you will copy the fork changes from. e.g. 0.7.2.2. It is made of 4 parts:
P1 is 0
P2 is 7
P3 is 2
P4 is 2
This documentation uses the N and P placeholders. You can replace them with the real digits to read version more easily:
(Optional) Copy this markdown file locally and change the version strings.
Copy the command below and update the 3rd part of each replacement operation with the appropriate version with the version part number that you identified here above. e.g. s/P2/7/g : the 7 should be another number now. The rest remains identical.
sed --in-place=.backup 's/0/0/g; s/N2/11/g; s/N3/1/g; s/P1/0/g; s/P2/7/g; s/P3/2/g; s/P4/2/g' /path/to/new-supported-version.md
Let's fork!
The newly forked repository will be called new-repo. This will be the name by which it is called in this procedure further on.
There will later be 2 other repo with different names.
The naming convention to identify a repo will be <name of the repo>/path/in/the/repo in the commands or file references.
I understand the naming convention.
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 v0.14.1.x and a new fork named v0.15.0.x into which we want to port the changes made in v0.14.1.x up to v0.14.1.1
Note: the branch names here are to be seen as references, so they should really be remotes/....
# ... 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/0.15.0 # 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 v0.15.0 of the branch that you want to fork from.
git tag --list
Create a new branch sovity/0.15.0 from that tag.
git checkout -b sovity/0.15.0 v0.15.0
Push this branch to the fork. It will be our new main for this fork version.
git push fork sovity/0.15.0:sovity/0.15.0
Checkout a new branch 0.15.0-fork-setup on the same commit as sovity/0.15.0.x.
git checkout sovity/0.15.0 (Optional, should already be on the correct branch)
git checkout -b 0.15.0-fork-setup
In gradle.properties, set the correct branch version: 0.15.0.1.
git remote show fork
* remote fork
Fetch URL: git@github.com:sovity/core-edc.git
Push URL: git@github.com:sovity/core-edc.git
HEAD branch: doesntMatter
Remote branches:
sovity/0.14.1 tracked
sovity/0.15.0 tracked
... more
Local branches configured for 'git pull':
sovity/0.15.0 merges with remote sovity/0.15.0
... more
Local refs configured for 'git push':
sovity/0.15.0 pushes to sovity/0.15.0 (up to date)
... more
Other resources
In a separate folder (we'll call it default-repo), check out the edc-core repository on the default branch. This will be useful to update the /.github/new-supported-version.md procedure. It is likely to change a bit on each fork.
I promise that I will update the procedure step by step.
Update the project
Before editing the code, check that your IDE has the correct editor settings (imports single classes, indents, ...). There is an resources/edc-codestyle.editorconfig file in the project.
Adjustments
Check out the changes that were made in the previous fork. They should be documented on the branch of the previous version in /docs/developer/fork/code-migration.md
cd new-repo && git show v0.14.1.1:docs/developer/fork/code-migration.md
Create the equivalent file in the new repo:
cd new-repo && git restore -s v0.14.1.1 -- docs/developer/fork/code-migration.md
Remember to copy and adapt each point that you use from that procedure in the new fork.
Read /docs/developer/fork/code-migration.md and apply it to the current branch.
You may want to check out the previous repo and diff between the 2 projects.
Update /docs/developer/fork/code-migration.md to reflect the situation in this new fork.
Run the tests locally and check that they all work. If not:
Try to fix the test if it's relevant for the changes that we want to do in the fork.
Consider adding @Disabled on the tests that we will likely not use or that would be hard to fix.
e.g. outdated certificates would be hard to regenerate and fix and could be disabled as long as our fork doesn't touch the parts of the code that use them.
Add a changelog CHANGELOG.md and the docs docs/developer/fork/* from the previous version 0.14.1.1
Here would be a great moment to commit the above changes as Migration baseline as we're now going in uncharted territories... 😉
For each of the former change in the /docs/developer/fork/changes.md
Check the bonus section above to find helpful commands.
Evaluate whether the change needs to be ported
Reasons for not porting may include
The code that the fork used no longer exist
The change or an equivalent was implemented upstream in a version before or including 0.15.0.
The change is no longer desired
...
Port the change if needed.
Update CHANGELOG.md.
Detail the change in the current documentation docs/developer/fork/changes.md. Check out the previous fork documentation for how to structure the document.
Implement the new changes that apply to this fork.
Delete the previous docs/developer/fork/v0.14.1.1.md notes after each element is either migrated or discarded.
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.
The naming scheme for the tagged and updated actions is fork version _ date at which the action was working _ -version.
e.g. 0.15.0_2025-06-07_1 for the latest main commit.
e.g. 0.15.0_2022.03.04_3 for the commit that was used during releasing, 3rd revision. Here the _3 is related to the actionsfork scripts and is independent of the 4th digit in the core-edcfork.
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 mainupstream 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 LATESTmain commit from upstream
git checkout upstream/main
git checkout -b pinned/0.15.0_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 0.15.0_LATEST_1 pinned/0.15.0_LATEST
Push that new tag to the sovity core edc github fork
git push fork tag 0.15.0_LATEST_1
Change all the action's @main version for the 0.15.0_LATEST_1 version
Change all the eclipse-edc/.github for sovity/core-edc-github
Adapt the publishing and promoting actions to the new core-edc's actions.
Branches starting with sovity/ must be published on the AzureTest instance.
Tags starting with v must be published on the Azure (non-test) instance.
Disable the jar signing
v0.2.1 / v0.7.2
The signing is managed in the EDC gradle plugin.
Add skip.signing=true to the gradle.properties
Test the publishing on the Azure Test instance, by publishing a branch starting by sovity/.
Create a PR with some changes to target the core-edc fork on a sovity/ branch and merge it.
Check that the artifacts have been deployed to the Azure Test repo
Update the release.md on the default branch.
You can now create PRs against sovity/0.15.0 with your desired changes, see the patch procedure
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.
Open a PR
Add a message in the PR: ⚠️⚠️ NO SQUASH COMMIT ON THIS ONE PLEASE ⚠️⚠️. This will help during the next migration by keeping roughly 1 commit for 1 change.
TODO
Add diffing verify.yml with previous version to add the branch triggers.
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.11.1 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 or removed.
In this procedure, we will work with the following repositories
Steps
Bonus
Helpful git commands. Just a few tips about the commands that could help. AI can probably help too. It will be mentioned later when these will be useful.
Find the common ancestor
For instance to know from which commit on the main branch a pinned version comes from.
git merge-base A Bfinds the last common commit between the referencesAandB.gitGraph commit commit id: "merge-base(A,B)" tag: "base" branch foo commit commit tag: "B" commit checkout main commit commit tag: "A" commitShow 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)' --allShow a different history
Shows the changes for a specific file that is on another branch.
git log ..VERSION -- FILEortig ..VERSION -- FILEe.g.
Cherry-picking
Select a change that was made in some commit with
git cherry-pickAlternatively, you may try a diff+apply+merge between the commits of the previous fork may be enough to port the change
git apply <(git diff vP1.P2... vP1.P2...).Fix the picking conflict
Open the merge diff in your prefered tool
Preview older revision
See what a folder looked like without checking it out
git ls-tree REVISION -- path/to/thinge.g.
git ls-tree v0.7.2.2 -- .github/workflows/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
NEXTis theupstreamversion that you want to fork from. e.g 0.11.1. It is made of 3 parts following parts:0is0N2is11N3is1PREVIOUSis the version that you will copy the fork changes from. e.g. 0.7.2.2. It is made of 4 parts:P1is0P2is7P3is2P4is2This documentation uses the
NandPplaceholders. You can replace them with the real digits to read version more easily:s/P2/7/g: the7should be another number now. The rest remains identical.sed --in-place=.backup 's/0/0/g; s/N2/11/g; s/N3/1/g; s/P1/0/g; s/P2/7/g; s/P3/2/g; s/P4/2/g' /path/to/new-supported-version.mdLet's fork!
The newly forked repository will be called
new-repo. This will be the name by which it is called in this procedure further on.There will later be 2 other repo with different names.
The naming convention to identify a repo will be
<name of the repo>/path/in/the/repoin the commands or file references.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
v0.14.1.xand a new fork namedv0.15.0.xinto which we want to port the changes made inv0.14.1.xup tov0.14.1.1Note: 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: "v0.14.0" branch upstream/bugfix/0.14.1 checkout upstream/bugfix/0.14.1 commit commit tag: "v0.14.1" branch fork/sovity/0.14.1 commit commit commit tag: "v0.14.1.1" checkout upstream/bugfix/0.14.1 checkout upstream/main commit commit commit tag: "v0.15.0" branch upstream/bugfix/0.15.0 checkout upstream/bugfix/0.15.0 commit tag: "v0.15.1" commit tag: "v0.15.2" commit tag: "v0.15.0" id: "to fork" branch fork/sovity/0.15.0 commit id: "new fork" commit tag: "v0.15.0.1" checkout upstream/main commit commitImportant
Note: the upstream branch name may vary:
remotes/upstream/release/0.10.0remotes/upstream/bugfix/0.7.2remotes/upstream/v0.6.5Make it work locally
This section describes the steps to prepare the fork and make it run locally.
Setup a repository
forkcore-edcinto thenew-repofolder.git clone --origin fork git@github.com:sovity/core-edc.git new-repo && cd new-repogit remote add upstream git@github.com:eclipse-edc/Connector.gitgit fetch --all --tagsSetup example
Your repository now looks like this:
In
new-repo:git remote -vgit branch -a# ...are comments to describe the situation and no part of the output.git tag -lThe 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.Establish the branches
v0.15.0of the branch that you want to fork from.git tag --listsovity/0.15.0from that tag.git checkout -b sovity/0.15.0 v0.15.0mainfor this fork version.git push fork sovity/0.15.0:sovity/0.15.00.15.0-fork-setupon the same commit assovity/0.15.0.x.git checkout sovity/0.15.0(Optional, should already be on the correct branch)git checkout -b 0.15.0-fork-setupgradle.properties, set the correct branch version:0.15.0.1.git remote show forkOther resources
default-repo), check out theedc-corerepository on thedefaultbranch. This will be useful to update the/.github/new-supported-version.mdprocedure. It is likely to change a bit on each fork.Update the project
resources/edc-codestyle.editorconfigfile in the project.Adjustments
/docs/developer/fork/code-migration.mdcd new-repo && git show v0.14.1.1:docs/developer/fork/code-migration.mdcd new-repo && git restore -s v0.14.1.1 -- docs/developer/fork/code-migration.md/docs/developer/fork/code-migration.mdand apply it to the current branch./docs/developer/fork/code-migration.mdto reflect the situation in this new fork.@Disabledon the tests that we will likely not use or that would be hard to fix.CHANGELOG.mdand the docsdocs/developer/fork/*from the previous version0.14.1.1git checkout v0.14.1.1 -- CHANGELOG.md docs/developer/fork/\*CHANGELOG.mdand keep the template.CI adjustments
java { withSourcesJar() }.github/workflows/verify.yaml, tasks:Publish-ArtifactsandPromote-Artifactsgit show v0.14.1.1:.github/workflows/verify.yaml | grep -A999 'Publish-Artifacts:'verify.ymlin the new fork.build.gradle.ktsmaven-publishpluginsettings.ktsCompare the verify.yml file between the new forked version and the previous version.
verify.ymlfile onsovity/*branches, PRs and tagsPort the code
Migration baselineas we're now going in uncharted territories... 😉/docs/developer/fork/changes.md0.15.0.CHANGELOG.md.docs/developer/fork/changes.md. Check out the previous fork documentation for how to structure the document.docs/developer/fork/v0.14.1.1.mdnotes after each element is either migrated or discarded.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
@mainversion in its CI, it is certain that the scripts that are the current@mainones 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
forkactionsrepositorygit clone --origin fork git@github.com:sovity/core-edc-github.gitupstreamactionsrepositorygit remote add upstream git@github.com:eclipse-edc/.github.gitgit fetch --all --tagsResult
git remote -vOverview
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: "0.15.0_LASTOK_1" branch fork/pinned/0.15.0_LASTOK commit tag: "0.15.0_LASTOK_2" commit tag: "0.15.0_LASTOK_3" checkout upstream/main commit commit commit commit id: "latest" tag: "0.15.0_LATEST_1" branch fork/pinned/0.15.0_LATEST commit tag: "0.15.0_LATEST_2" commit tag: "0.15.0_LATEST_3"LATESTandLASTOKare iso datesYYYY-MM-DDThe naming scheme for the tagged and updated actions is
fork version_date at which the action was working_-version.e.g.
0.15.0_2025-06-07_1for the latest main commit.e.g.
0.15.0_2022.03.04_3for the commit that was used during releasing, 3rd revision. Here the_3is related to theactionsforkscripts and is independent of the 4th digit in thecore-edcfork.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
LATESTis the last commit on themainupstreambranch.LATESTin this file by the date you find. The date part should be enough.git show --no-patch --format=%ci upstream/mainsed --in-place 's/LATEST/2025-06-07/g' fork.mdLASTOKis optional and will be defined later.Pin the action versions
LATESTmaincommit fromupstreamgit checkout upstream/maingit checkout -b pinned/0.15.0_LATESTgit push forkcore edc fork branch_today_1git tag 0.15.0_LATEST_1 pinned/0.15.0_LATESTgit push fork tag 0.15.0_LATEST_1@mainversion for the0.15.0_LATEST_1versioneclipse-edc/.githubforsovity/core-edc-githubeclipse-edc/.github/.github/workflows/task.yml@mainsovity/core-edc-github/.github/workflows/task.yml@0.15.0_LATEST_1eclipse-edc/.github/(.*)@mainwithsovity/core-edc-github/$1@0.15.0_LATEST_1From here we have:
Adjust the pinned main
pinned/0.15.0-LATESTbranch0.15.0_LATEST_(N+1)in theactionsrepo@0.15.0_LATEST_Nto0.15.0_LATEST_(N+1)Lost action
This part describes how to find where a missing action was and how to make it work again.
LASTOKwhen thecore-edcversion was released either with:git log --oneline --follow -- '.github/actions/THEACTIONNAME'git show --no-patch --format=%ci v0.15.0in thecore-edcrepo. e.g2022-03-04LASTOKwith the date you found.forkactionrepository the commit on the main branch that happened right before the timethe tagged commit in the core EDC was created.
git log --date=iso -n LINES --before="LASTOK"git log --date=iso -n 2 --before="2022-03-04"LINESto show more than 1 line.pinned/0.14.1_LASTOKfrom this older commit0.14.1_LASTOK_1e.g.0.14.14_2022-03-04_1actionsforkgit push fork tag 0.14.1_LASTOK_1core-edcforkfrom the pinned latest to that new version.Publishing
0.7.2.x: publishing and promotinggit checkout sovity/0.7.2 -- .github/workflows/verify.yml build.gradle.kts0.2.1.x: publishinggit checkout sovity/0.2.1 -- .github/workflows/publish.yml build.gradle.ktscore-edc's actions.sovity/must be published on theAzureTestinstance.vmust be published on theAzure(non-test) instance.v0.2.1/v0.7.2skip.signing=trueto thegradle.propertiessovity/.core-edcfork on asovity/branch and merge it.release.mdon the default branch.sovity/0.15.0with your desired changes, see the patch procedureFinalization
⚠️⚠️ NO SQUASH COMMIT ON THIS ONE PLEASE ⚠️⚠️. This will help during the next migration by keeping roughly 1 commit for 1 change.TODO
Add diffing
verify.ymlwith previous version to add the branch triggers.