DOC: improve docs on patching on the release branch. #5339
Conversation
Make a clear separate H3 heading, enumerate steps needed.
github-actions
bot
added
type:Documentation
|
|
||
| Here are the recommended steps to merge a topic to both `release` and `master` | ||
| branches, assuming the topic branch is forked off the `release` branch: | ||
|
|
There was a problem hiding this comment.
I think this should clearly state that a topic to be merged for a patched release should be based on release-X.X and a PR made into release-X.X. Although I'm not 100% what is what should be done.
There was a problem hiding this comment.
The branch base is documented here:
https://docs.itk.org/en/latest/contributing/index.html#create-a-topic
It could be changed to release-X.X.
| ``` | ||
|
|
||
| then: | ||
| 4. Finally, merge the `release` branch back into the `master` branch: |
There was a problem hiding this comment.
When a bug fix is cherry-picked from the master and then pushed onto the release branch, is it still useful to merge the release branch back to the master?
There was a problem hiding this comment.
I think so, mainly for avoiding merge conflicts in the future. If there are any merge conflicts, they are best tackled soon after the commits which cause them have been integrated.
There was a problem hiding this comment.
Yes, conflicts should be addressed and the Git commit history, a directed acyclic graph (DAG) and Merkle Tree, should keep the master, release, release-X.X branches connected.
|
|
||
| Here are the recommended steps to merge a topic to both `release` and `master` | ||
| branches, assuming the topic branch is forked off the `release` branch: | ||
|
|
There was a problem hiding this comment.
The branch base is documented here:
https://docs.itk.org/en/latest/contributing/index.html#create-a-topic
It could be changed to release-X.X.
| to merge the topic into the `release` and `release-X.X` branches, where `X.X` | ||
| is the current maintenance version (e.g., `5.4`): | ||
|
|
||
| 1. Ensure the topic branch is forked off the `release` branch. |
There was a problem hiding this comment.
If it is branched from release, then it should be merged into release first.
There was a problem hiding this comment.
When should a branch be based on release vs release-X.X? Additionally if the branch is based on release, does anything get merged into release-X.X?
There was a problem hiding this comment.
We currently have the workflow set up to be based on release by default, which is simpler and is easier to be consistent. Yes, if it is based on release, then it currently also gets merged to release-5.4.
There was a problem hiding this comment.
So "release" points to the current release, and release-X.X points to version specific release.
So would it be correct to say that when a patch is for the most recent release, that the patch should be based on the release branch, and merged into the release branch. And Only if a patch is for prior release, then the patch should be based off the older release-X.X?
Then current release-X.X could be ff merged along release. But patches to old-release-X.X would need to be merged into first into old-release-X.X, then release, then master.
I'm not sure if I am the one who should be writing this as I'm unsure to the expected processes.
There was a problem hiding this comment.
Yes, I would like if we had to typically maintain only two branches: master and release, and the most recent release-X.X just tracking (via fast forward) release. Currently release-X.X has history that is somewhat independent/different from release, despite having identical content. Matt, can you remind us of the reason why? And can we just switch to release-5.4 being just a pointer to release?
There was a problem hiding this comment.
We have an overview of the branches and their purpose here:
https://docs.itk.org/en/latest/contributing/index.html#branches
The release branch tracks the code in Git of what has been released or will be released in the next patch release. It is a "stable" version people can clone / checkout.
release-4.13, release-5.4 are different -- they are used to keep the history for ITK 4 series ITK 5 series.
So would it be correct to say that when a patch is for the most recent release, that the patch should be based on the release branch, and merged into the release branch. And Only if a patch is for prior release, then the patch should be based off the older release-X.X?
Yes, if a patch is for an older release, it can be based off that release's branch.
To make things more clear and direct, we could update the documentation to explicitly say , "branch off release-5.4 if your patch applies to ITK 5".
| ``` | ||
|
|
||
| then: | ||
| 4. Finally, merge the `release` branch back into the `master` branch: |
There was a problem hiding this comment.
Yes, conflicts should be addressed and the Git commit history, a directed acyclic graph (DAG) and Merkle Tree, should keep the master, release, release-X.X branches connected.
Make a clear separate H3 heading, enumerate steps needed.
PR Checklist
Refer to the ITK Software Guide for
further development details if necessary.