Backport guidelines
Context
In theory, Tiki master (formerly trunk on SVN) should be kept stable enough for dogfooding. In practice, that would be risky. And thus, many community members prefer to use stable versions, and just backport the fixes.
Backports take time, and can introduce regressions, which eats us time. Backports should never be a systematic, mechanical thing. There should be a reason for a backport. That time is better invested in fixing more bugs in master.
And the more the stable branch and master diverge, the more difficult and risky it becomes. On the other hand, the sooner fixes and enhancements are in a stable branch, the sooner they are available to end users.
So what is the right balance? We have some high-level guidelines at Where to commit. This page will help with more explanations.
For example, the Tiki26 release cycle was exceptional in that
- We increased the requirements from PHP 7.4 to 8.1
- We started Using GlitchTip as part of the Tiki development process
- We added PHPStan and Rector
- In May 2023 (the month before branching 26x), we broke the record for the number of monthly commits.
Types of commits
Changes to the database structure
In general, these should not be backported. We've have too many problems in the past. Please see: Database Schema Upgrade
Fatal error
Should be backported
Bug
Major: Can be backported.
Minor: Do you really need to backport? The next version will soon be upon us.
New feature
If self-contained, low risk and important to a specific project (client, dogfood for tiki.org, etc.), can be backported (when not in a Freeze and Slush period)
Warnings
With default error reporting settings, warnings are generally only visible to admins. Fix these in the stable branch if you are nearby - not essential for the .0 release, but nice to have one day.
Deprecation warnings
- What do we do about a deprecation warning to PHP 8.2? (We are running PHP 8.1 for many sites, but we are hoping it works OK in PHP 8.2)
- Nice to have one day
- What do we do about a deprecation warning but that we don't know in which PHP version it will stop working?
- Act casual, hope no one notices 😁
- Act casual, hope no one notices 😁
Merging and cherry-picking
- I propose that we allow [FIX] (etc) commits directly into 26.x and then use
git mergeback into trunk/master to make sure all changes are contained in future versions. Cherry-picking from trunk to 26.x should still be ok and shouldn't create conflicts if done cleanly.- @Jonny Bradley: Would you envisage something like the script we had for Semi-automatic merging period or each committer is responsible to track?
- I am worried about omissions and merge conflicts. To keep things simpler, and reduce odds of merge conflicts maybe everyone could make an effort to focus on 26x and any 27x destined work could stay in GitLab draft merge requests until 26.0 is released? And thus, most/all merge conflict resolution would fall on 27x, where we have plenty of time.
- @Jonny Bradley: Would you envisage something like the script we had for Semi-automatic merging period or each committer is responsible to track?
- This is slightly different to the past couple of releases (always commit in trunk first then cherry-pick) and a little more like how we did it in
svndays, and should allow for easier and quicker testing of fixes on real/staging sites running on 26.x before 26.0 release.- @Jonny Bradley: For Pre-dogfood servers for Tiki 26 release process, we'll have a fairly easy way to test, but I agree that for the community at large, it's easier to just focus on 26.
- I'd rather stay with commit-to-master and then backport to previous stable/supported branches back to whatever is needed. Otherwise, we risk loosing updates in upcoming versions if someone forgets to cherry-pick to master.
- Fair enough, but wouldn't doing
git mergeperiodically from 26.x to master catch anything that was missed?
- Fair enough, but wouldn't doing
- I feel (strongly) the we should keep cherry-picking
- On the other hand, I don't care which direction we cherry pick to. It's more logical to do user bug fixes on 26.x since one can relatively use the same database to test in master, while the reverse is not true. As long as it's a rule that you are not done until you merge a change back into master, or wrote in the commit message that it's unnecessary or unwanted in master.
- I do not see how merging back could work, especially since the master branch is in the middle of refactoring. Say someone fixes a bug in master (commit A). Then cherry picks in 26.x to backport, but have to do changes (say a variable or function name) because master diverged (this isn't a merge conflict). He does commit B in 26.x (say "Use old variable name for X). He is done, everything is fine. The another developper comes along and fixes an unrelated bug directly in 26.x (commit C). He then merges in master. Commit B gets pulled along, and master is now broken, in a completely unerelated place.
- We use a linear history process for master (we use rebase on merge requests by default). I do not know of any way git can keep track that commit B above is still commit B when "merging" into master. Cherry-pick doesn't have that problem as far as I know.
- Halting merging merge request into master means (in practice) halting almost all fundamental work in master (everything that affects a lot of files), as if the changes are not merged regularly, not only will there be more and bigger conflicts once they do merge, but there is a lot more chance of the merge being incorrect. For example (not that it is especially likely example, just an easy one to understand), if master renames a global variable, and a merge request newly uses a global variable (and that is frequent, prefs...), the code won't work once merged, even if there is no merge conflict.
- 2023-06-12: Victor, Jonny, Roberto and Marc discussed: We can try this commit-to-26x process for this version, and evaluate after. (TODO update Where To Commit)
- 2023-06-12: Victor, Jonny, Roberto and Marc discussed: We can try this commit-to-26x process for this version, and evaluate after. (TODO update Where To Commit)
A message form Benoit about backports
A change of policy: I will no longer merge MRs that are backports (unless they are tagged Urgent, or I'm assigned as reviewer, but if so I expect to find a comment in the MR or linked ticket that explains why it's urgent or needs my eyes). There is a number of reasons for that.
1- The first and most important one is that I don't have the capacity to do a good job of it. I recently merged backports that I shouldn't (for varying reasons).
2- Backports should never be a systematic, mechanical thing. There should be a REASON for a backport. Sometimes it's implicit (such as during branch stabilisation period), but there has to be one!
3- Even when there is a reason, it is not normal for most backports to go in the same day without some testing in master. It is not forbidden, but it is not normal. Doing a MR, backporting, finding bugs, fixing the original MR, backporting wastes multiple people's time, including the original author's. Is much easier to test for a while, fix what needs fixing, then backport once in MRs that each contain multiple cherry picks in a single merge request.
4- The judgement call to backport or not depends on context only, or mostly the original author has. (It it done as part of an ongoing client project, a dependency for something else, was it actually originally developed and tested in a past branch and just now being upstreamed, etc.
5- I simply cannot afford the time for discussions like "follow the backport chain, hey, tests must pass before I merge, etc.)
So, if you've been here a while, do take responsibility to self merge backports if you feel confident doing so. Mistakes happen, but if you are the original author, self-merging means you at least commit to supporting the MR in that branch.
If you are not confident, ask someone else to look at it. And please have an idea of who may be able to promptly look at it, before you create the backport MR to avoid hogging the merge request queue (it's ok not to create it immediately, we have tags to remind us). Typically that will be your coach, or a developer in the same office. Assign that person as reviewer.
Reviewing a backport is different than an original MR. While it's good to find additional issues in the original MR in this second review, and it does occasionally happen, that's not primarily what you are looking for. When you review a backport you are looking for:
- Undetected merge errors (remnants of another MR, etc.) in the diff, accidental reverts of generated files, etc.
- Checking that the backport chain was followed, especially for new devs (the description doesn't lie, the original MR was actually merged, the merge commit in the previous branch was what was cherry picked, etc.
- Backporting makes sense in the first place (for example in the past I've seen non-conflicting fixes for features that didn't exist back in the old branch), and that there is a reason for the backport (ideally that reason should be communicated...)
I will off course continue to review any merge request where the first reviewer feels he needs a second review, including backports.
Consolidating backports
If you have a large number of related backports, it can make sense to consolidate (but not squash). Ex.: https://gitlab.com/tikiwiki/tiki/-/merge_requests/8970
Backport chain procedure (Best Practice)
First, tag the merge request with "CherryPickDownTo" label only on the master MR (or the highest version if master does not apply for whatever reason) to indicate which version should the MR be backported down to.
In our procedure, each backport should originate from the supported branch directly above the target branch. This ensures clean commit history and minimizes divergence between versions.
For example:
Backport to 27.x → cherry-pick (source) from 28.x (except when the 28.x became EoL, then cherry-pick from 29.x directly)
Backport to 26.x → cherry-pick (source) from 27.x
The goal is to preserve consistency and avoid regression risks introduced by cherry-picking from non-adjacent branches.
By following the direct-upstream rule, developers ensure that:
- Each stable branch contains only commits from its immediate successor.
- Future merges and cherry-picks remain predictable and traceable.
The “CherryPickDownTo” labels (e.g., CherryPickDownTo 27.xLTS) accurately reflect the logical flow of changes.
Example
If a fix was merged into 28.x and needs to be included in the long-term support branch 27.x, do the following:
git checkout 27.x
git cherry-pick <commit-hash-from-28.x>
Notes
Avoid cherry-picking directly from master or skipping versions. The only exception to skip a branch is when the Tiki version in between becomes EoL.