@@ -29,13 +29,13 @@ CMAKE_BUILD_PARALLEL_LEVEL=40 cmake --build .
2929
3030### How does this work?
3131
32- In the following we will use ` 1.1.1 ` as the latest stable release (LSR).
32+ In the following we will use ` 1.2.0 ` as the latest stable release (LSR).
3333
3434The workflow entails these steps:
35351 . Download and unzip the LSR.
36362 . Remove everything from the LSR except the tests in ` <sharg_lsr_source>/test/ ` .
37373 . Apply patches from the current git version on the LSR, i.e., patches found in
38- ` <sharg_git_source>/test/api_stability/1.1.1 ` .
38+ ` <sharg_git_source>/test/api_stability/1.2.0 ` .
3939 * These patches will only apply changes on the tests.
4040 * This step is necessary as some of our tests also test non-public / non-stable API.
41413 . Use the current version of ` find_package (Sharg) ` found in ` <sharg_git_source>/cmake ` .
@@ -84,25 +84,50 @@ There are two categories of API changes that are reflected in the patches (prefi
8484
8585### How to create patches?
8686
87- In the following, we will use ` 1.1.1 ` as the latest stable release (LSR).
87+ < details >< summary >Click for tl;dr< summary >
8888
89- Create a new branch based on the LSR and apply all existing patches in ` <sharg_git_source>/test/api_stability/1.1.1 ` .
89+ ``` bash
90+ git update-ref -d refs/heads/api-stability-patches
91+ mkdir -p /tmp/sharg-api-stability-patches
92+ cp -u=all test/api_stability/1.2.0/* .patch /tmp/sharg-api-stability-patches
93+ git checkout -b api-stability-patches 1.2.0
94+ git am --keep-non-patch /tmp/sharg-api-stability-patches/* .patch
95+ rm -f /tmp/sharg-api-stability-patches/* .patch
96+
97+ git cherry-pick < commit>
98+
99+ git format-patch 1.2.0
100+ mv * .patch /tmp/sharg-api-stability-patches
101+ git checkout -
102+ cp -u /tmp/sharg-api-stability-patches/* .patch test/api_stability/1.2.0/
103+ rm -rf /tmp/sharg-api-stability-patches
104+ git branch -D api-stability-patches
105+
106+ git add test/api_stability/1.2.0/
107+ git commit
108+ ```
109+
110+ </details >
111+
112+ In the following, we will use ` 1.2.0 ` as the latest stable release (LSR).
113+
114+ Create a new branch based on the LSR and apply all existing patches in ` <sharg_git_source>/test/api_stability/1.2.0 ` .
90115
91116```
92117cd <sharg_git_source>
93118
94119# copy over patches to a tmp directory (`git am` seems to not support applying patches onto a different branch)
95120mkdir -p /tmp/sharg-api-stability-patches
96- cp test/api_stability/1.1.1 /*.patch /tmp/sharg-api-stability-patches
121+ cp test/api_stability/1.2.0 /*.patch /tmp/sharg-api-stability-patches
97122
98123# create a new branch based on the LSR and switch to it
99- git checkout -b api-stability-patches 1.1.1
124+ git checkout -b api-stability-patches 1.2.0
100125
101- # apply all patches onto 1.1.1 (--keep-non-patch will keep `[NOAPI]` tags in the commit message)
126+ # apply all patches onto 1.2.0 (--keep-non-patch will keep `[NOAPI]` tags in the commit message)
102127git am --keep-non-patch /tmp/sharg-api-stability-patches/*.patch
103128
104129# clean up applied patches
105- rm /tmp/sharg-api-stability-patches/*.patch
130+ rm -f /tmp/sharg-api-stability-patches/*.patch
106131```
107132
108133Now re-apply the commit(s) that changed the API.
@@ -129,8 +154,8 @@ It is also important that you double check if the patch only contains changes th
129154After that, we can export all patches.
130155
131156```
132- # export all patches since 1.1.1
133- git format-patch 1.1.1
157+ # export all patches since 1.2.0
158+ git format-patch 1.2.0
134159
135160# move them to tmp directory
136161mv *.patch /tmp/sharg-api-stability-patches
@@ -141,15 +166,18 @@ Now change to your branch that you were working on and check-in the patches.
141166```
142167git checkout -
143168
144- cp /tmp/sharg-api-stability-patches/*.patch test/api_stability/1.1.1 /
169+ cp -u /tmp/sharg-api-stability-patches/*.patch test/api_stability/1.2.0 /
145170
146171rm -rf /tmp/sharg-api-stability-patches
147172
148173# add new patches
149- git add test/api_stability/1.1.1 /
174+ git add test/api_stability/1.2.0 /
150175
151176# commit changes
152177git commit
178+
179+ # delete local branch
180+ git branch -D api-stability-patches
153181```
154182
155183Before pushing, try whether the patches work as intended.
0 commit comments