Backporting guidelines

Preliminaries

Both new features and bug fixes should be backported to older branches (7.0+, not to 6.0!), if the changes maintain source and binary compatibility. Mechanized checks are available only for the second criterion, by invoking mimaReportBinaryIssues. Source compatibility needs to be checked by careful investigation of the diff. In many cases, binary implies source compatibility, but not always.

What to backport

Candidates are commits which add

• top-level classes, traits and objects
• (implemented) methods to objects and classes

You can also add methods to sealed traits, but Migration Manager will complain (because of potential breakage when used from plain Java). It is possible to add exceptions, though, but usually it's not that important to include each and every potential backport.

Preparation

For each pending maintenance release, we keep a list of pull requests and commits which have accumulated in the development branch since the last maintenance release (e.g. #665). This list should be kept up-to-date. If a new pull request or bare commit comes in, make an educated guess whether its backportable (you don't need to attempt it right away), and if it is likely to not break compatibility, add it to the list.

Larger additions (e.g. IList) can be added as a bulk item.

How to backport

Some general notes first: Backporting is not an exact science, and sometimes requires tradeoffs. When in doubt, don't backport. If necessary, don't backport a commit or a pull request in full, but only parts of it (but please make sure to document it in the commit message). Try to preserve the author of the original commit(s). cherry-pick does this automatically, but if you commit manually, you might need to specify --author. If you have to change the commit significantly, it's okay to have your name as author. In that case, please include the original author in the commit message, like so (e.g. 09324f1fb1), and document your changes:

Original commit by @<username>
<old-commit-message>

Changes to the original commit:
- ...

Backporting usually consists of these steps, depending on what you are backporting:

• A bare commit (not from a pull request): Just call git cherry-pick --edit <commit-id>. Add the following line at the end of the commit message:

  Cherry-picking <commit-id>

  Multiple commits, if related, can be rolled into one backport commit (e.g. 2cac4469e8). You can use a sequence of git cherry-pick --no-commit commands to do that. After you're done, use git commit and try to find a commit message which roughly describes the common idea of all of the backported commits, but don't copy all original messages verbatim. Make sure to include all original commit IDs in the last line of the message.

• Commits from a pull request: Figure out which commits can be backported. If it's just a single one or multiple ones but not all of them, proceed like above. In the latter case, a good commit message is the title of the pull request.

  For backporting a pull request in full, you can use GitHub to obtain the full diff by appending .diff to the pull request URL (e.g. 752.diff). Apply the patch to the code base with git apply --reject and manually merge the rejected parts.

  When committing the backported patches, include the following line in the commit message (e.g. 18b86d36e5):

  Cherry-picking pull request <pull-request> (<commit-id-1>, <commit-id-2>, ...)

  In the rare event that a pull request contains commits by multiple different authors, you can still roll them into one: Either use the majority author, or list all authors in the commit message (whatever fits best).

• Bulk items: Copy whole the corresponding files in the maintenance branch. Write a commit message which looks like this (e.g. 1710912021):

backport from Based on commit .

Once you're done, run the migration manager tests. If that works without problems, submit a pull request to the correct branch. Your help is much appreciated!