tpm2-tss
tpm2-tss copied to clipboard
tpm2-software
doc: Document branching strategy
TPM2 projects have been used as an example of best practices many times and we've been asked what the branching strategy is. We believe this is an accurate description of how release branches and tags are created and patches are applied. Please review and let us know how we can get to a place where we have accurate docs on the process.
Codecov Report
:exclamation: No coverage uploaded for pull request base (
master@1716129). Click here to learn what that means. The diff coverage isn/a.
:exclamation: Current head afc68a2 differs from pull request most recent head 9b213f1. Consider uploading reports for the commit 9b213f1 to get more accurate results
@@ Coverage Diff @@
## master #2330 +/- ##
=========================================
Coverage ? 83.45%
=========================================
Files ? 349
Lines ? 37665
Branches ? 0
=========================================
Hits ? 31433
Misses ? 6232
Partials ? 0
:mega: Codecov can now indicate which changes are the most critical in Pull Requests. Learn more
![codecov[bot] avatar](https://avatars.githubusercontent.com/in/254?v=4 "Published by a pub.dev verified publisher"){kind=small}
I think I'm too stupid to understand anything beyond the first picture. For the first picture though: There is no relation between 1.0.x and 1.1.x because the both branch off of master
master ---------------------------------->
\ \--------------> 1.1.x
\-------------------------> 1.0.x
This is also why IMHO there cannot be a 1.x branch with a consistent history. If 1.x was at one point equal to 1.0.x then after 1.1.x release you'd have to either merge 1.1.x continuously or you'd have to hard-reset 1.x to 1.1.x (forcing all consumers to also hard-reset) (This is why I don't provide one)
So I'd simply describe it like this:
----- 1.0.0-rc0 ---- 1.0.0 ------- 1.1.0 -------------------------------------------------> master
\ \
\ \ 1.1.0 ---------------------- 1.1.1 ----------------> 1.1.x
\
\ 1.0.0 ------------- 1.0.1-rc0 --- 1.0.1 ------ 1.0.2 ----------> 1.0.x
Major and minor releases are tagged/released from master (including the RC-phase).
Upon release, a release-stable-branch is created. Upon creation the branch points to the tagged release commit.
The release-tagged is the last common commit of the master and the stable branch.
Bugfix releases are tagged/released from the stable-branches (including the RC-phase)
Updates to the release-stable-branch are typically (but not necessarily) cherry-picks from master.
It cant be that:
----- 1.0.0-rc0 ---- 1.0.0 ------- 1.1.0 -------------------------------------------------> master
\ \
\ \ 1.1.0 ---------------------- 1.1.1 ----------------> 1.1.x
\
\ 1.0.0 ------------- 1.0.1-rc0 --- 1.0.1 ------ 1.0.2 ----------> 1.0.x
The tags for 1.1.0 can't point to two commits. Even if the contents are the same, the git sha is based on the parent. So the graph above I think would be:
----- 1.0.0-rc0 ---- 1.0.0 ------------>------------------------------>--------------> master
\ \ / /
\ \ 1.1.0 / ---------------------- 1.1.1 /----------------> 1.1.x
\
\ 1.0.0 ------------- 1.0.1-rc0 --- 1.0.1 ------ 1.0.2 ----------> 1.0.x
It's important to note some of the release branches need a git merge back into master to keep git describe functioning properly, even if the only incoming changes are the CHANGELOG.
It cant be that:
The tags for 1.1.0 can't point to two commits. Even if the contents are the same, the git sha is based on the parent. So the graph above I think would be:
Well, true, I guess this would be more correct:
----- 1.0.0-rc0 ---- 1.0.0 ------- 1.1.0 -------------------------------------------------> master
| |
| 1.1.0 -------------------------- 1.1.1 ----------------> 1.1.x
|
1.0.0 -------------------- 1.0.1-rc0 --- 1.0.1 ------ 1.0.2 ---------> 1.0.x
It's important to note some of the release branches need a git merge back into master to keep git describe functioning properly, even if the only incoming changes are the CHANGELOG.
On the tpm2-tss I've never done a merge back. The CHANGELOG was just copied to master; or as mentioned, I cherry-pick from master to the stables. We used to have the policy of rebase-only merges, in the past for a non-divergent history (introduced by Phil) and I have to say, I like it.
Thank you for the comments! We’ll update the diagram accordingly.
On Tue, Jun 14, 2022 at 05:04 Andreas Fuchs @.***> wrote:
It cant be that:
The tags for 1.1.0 can't point to two commits. Even if the contents are the same, the git sha is based on the parent. So the graph above I think would be:
Well, true, I guess this would be more correct:
----- 1.0.0-rc0 ---- 1.0.0 ------- 1.1.0 -------------------------------------------------> master | | | 1.1.0 -------------------------- 1.1.1 ----------------> 1.1.x | 1.0.0 -------------------- 1.0.1-rc0 --- 1.0.1 ------ 1.0.2 ---------> 1.0.x
It's important to note some of the release branches need a git merge back into master to keep git describe functioning properly, even if the only incoming changes are the CHANGELOG.
On the tpm2-tss I've never done a merge back. The CHANGELOG was just copied to master; or as mentioned, I cherry-pick from master to the stables. We used to have the policy of rebase-only merges, in the past for a non-divergent history (introduced by Phil) and I have to say, I like it.
— Reply to this email directly, view it on GitHub https://github.com/tpm2-software/tpm2-tss/pull/2330#issuecomment-1155093522, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABNMXYNO4YA6Y275KRFA6C3VPBYOPANCNFSM5RDACRNQ . You are receiving this because you authored the thread.Message ID: @.***>
On the tpm2-tss I've never done a merge back. The CHANGELOG was just copied to master; or as mentioned, I cherry-pick from master to the stables. We used to have the policy of rebase-only merges, in the past for a non-divergent history (introduced by Phil) and I have to say, I like it.
That's no longer true, because consider this scenario:
------> 3.0.0 ----> master (git describe is 3.0.0-X...)
\
\------3.1.0 ---->
Consider the case where patches are cherry-picked from 3.1.0 back to master, so master contains all of 3.1.0, git describe output is still lagging. Which means pkg-config if you depend on something lets say in 3.1.0, master will fail even though it has the commit.
On the tpm2-tss I've never done a merge back. The CHANGELOG was just copied to master; or as mentioned, I cherry-pick from master to the stables. We used to have the policy of rebase-only merges, in the past for a non-divergent history (introduced by Phil) and I have to say, I like it.
What we don't want to do is merge every PR, but merging stable branches back to master is fine.
On the tpm2-tss I've never done a merge back. The CHANGELOG was just copied to master; or as mentioned, I cherry-pick from master to the stables. We used to have the policy of rebase-only merges, in the past for a non-divergent history (introduced by Phil) and I have to say, I like it.
That's no longer true, because consider this scenario:
------> 3.0.0 ----> master (git describe is 3.0.0-X...) \ \------3.1.0 ---->Consider the case where patches are cherry-picked from 3.1.0 back to master, so master contains all of 3.1.0, git describe output is still lagging. Which means pkg-config if you depend on something lets say in 3.1.0, master will fail even though it has the commit.
You graph cannot happen. The stable branch cannot be ahead of master in terms of major or minur version number. A stable would be ahead in terms of bug-fix version:
------> 3.0.0 ----> master (git describe is 3.0.0-X...)
\
\------3.0.1 ---->
This is possible.... Question is, if you ever have an application checking for a bugfix-version via pkg-config ? So far I only know of major or minor version checks, since they are features. Bugfix releases don't implement features...
On the tpm2-tss I've never done a merge back. The CHANGELOG was just copied to master; or as mentioned, I cherry-pick from master to the stables. We used to have the policy of rebase-only merges, in the past for a non-divergent history (introduced by Phil) and I have to say, I like it.
That's no longer true, because consider this scenario:
------> 3.0.0 ----> master (git describe is 3.0.0-X...) \ \------3.1.0 ---->Consider the case where patches are cherry-picked from 3.1.0 back to master, so master contains all of 3.1.0, git describe output is still lagging. Which means pkg-config if you depend on something lets say in 3.1.0, master will fail even though it has the commit.
You graph cannot happen. The stable branch cannot be ahead of master in terms of major or minur version number. A stable would be ahead in terms of bug-fix version:
------> 3.0.0 ----> master (git describe is 3.0.0-X...) \ \------3.0.1 ---->This is possible.... Question is, if you ever have an application checking for a bugfix-version via pkg-config ? So far I only know of major or minor version checks, since they are features. Bugfix releases don't implement features...
I should have made that a major version bump, but the overall problem stands. And yes certain bugs are worked around in tpm2-pytss for FAPI
_check_bug_fixed(
fixed_in="3.2",
backports=["2.4.7", "3.0.5", "3.1.1"],
details="Faulty free of FAPI Encrypt might lead to Segmentation Fault. See https://github.com/tpm2-software/tpm2-tss/issues/2092",
)
@pdxjohnny looking at this it appears correct. I think folks may find references to "main branch" confusing since it's the "master branch" in this repo and we have no intentions to rename it (too many things break). Can you update those references to reflect the current state of branch naming?
Sorry for being late to the party. Is there a reason why we are not using the mermaid gitGraph feature? I haven't spent a ton of time with this PR, but I find it a but hard to understand, tbh.
Stolen from here:
gitGraph:
commit "Ashish"
branch newbranch
checkout newbranch
commit id:"1111"
commit tag:"test"
checkout main
commit type: HIGHLIGHT
commit
merge newbranch
commit
branch b2
commit
Sorry for being late to the party. Is there a reason why we are not using the mermaid
gitGraphfeature? I haven't spent a ton of time with this PR, but I find it a but hard to understand, tbh.
Probably just didn't know it existed. That looks way nicer.
Yeah i think at time of writing that feature didnt exist
On Sat, Jul 8, 2023 at 08:25 William Roberts @.***> wrote:
Sorry for being late to the party. Is there a reason why we are not using the mermaid gitGraph feature? I haven't spent a ton of time with this PR, but I find it a but hard to understand, tbh.
Probably just didn't know it existed. That looks way nicer.
— Reply to this email directly, view it on GitHub https://github.com/tpm2-software/tpm2-tss/pull/2330#issuecomment-1627378796, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABNMXYNRUSRTXXBOLVHGUMLXPF3WRANCNFSM5RDACRNQ . You are receiving this because you were mentioned.Message ID: @.***>
@pdxjohnny I really want to see this merged, so I built a few graphs. I'm sure your graphs were a lot of work, so this might sweeten the deal to use the new format :)
Starting point
gitGraph
commit id: "feature (a27dbae3)" tag: "1.0.0"
commit id: "fix (e13eb557)" tag: "1.0.1"
checkout main
commit id: "feature (d18973ae)" tag: "1.1.0"
Release Branch
Someone finds a bug in 1.0.1 which does not occur in 1.1.x. We need to create a branch 1.0.x and fix it there.
gitGraph
checkout main
commit id: "feature (a27dbae3)" tag: "1.0.0"
commit id: "fix (e13eb557)" tag: "1.0.1"
branch 1.0.x
checkout main
commit id: "feature (d18973ae)" tag: "1.1.0"
checkout 1.0.x
commit id: "fix (g47ae21d)" tag: "1.0.2"
Cut Off Branch
Someone finds a bug in 1.1.0 which does not occur in e7612ba4. We have a choice.
Option A
As above, we can create another release branch.
gitGraph
commit id: "feature (a27dbae3)" tag: "1.0.0"
commit id: "fix (e13eb557)" tag: "1.0.1"
branch 1.0.x order: 3
checkout main
commit id: "feature (d18973ae)" tag: "1.1.0"
branch 1.1.x order: 2
checkout 1.0.x
commit id: "fix (g47ae21d)" tag: "1.0.2"
checkout main
commit id: "refactor (e7612ba4)"
checkout 1.1.x
commit id: "fix (5d26eadd)" tag: "1.1.1"
Option B
Or we end support for 1.1.x and release 1.2.0.
gitGraph
commit id: "feature (a27dbae3)" tag: "1.0.0"
commit id: "fix (e13eb557)" tag: "1.0.1"
branch 1.0.x
checkout main
commit id: "feature (d18973ae)" tag: "1.1.0"
checkout 1.0.x
commit id: "fix (g47ae21d)" tag: "1.0.2"
checkout main
commit id: "refactor (e7612ba4)" tag: "1.2.0"
Backport
We chose option B. Now we fix a bug in 1.2.0. If we also want to fix that in 1.0.2, we need to backport the fix via a cherry-pick.
gitGraph
commit id: "feature (a27dbae3)" tag: "1.0.0"
commit id: "fix (e13eb557)" tag: "1.0.1"
branch 1.0.x
checkout main
commit id: "feature (d18973ae)" tag: "1.1.0"
checkout 1.0.x
commit id: "fix (g47ae21d)" tag: "1.0.2"
checkout main
commit id: "refactor (e7612ba4)" tag: "1.2.0"
commit id: "fix (3fc8d188)" tag: "1.2.1"
checkout 1.0.x
cherry-pick id: "fix (3fc8d188)" tag: "1.0.3"