Merging breaking changes of internal API: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Created page about getting breaking changes into Qt)
 
mNo edit summary
Line 1: Line 1:
While public API cannot be removed outside of a new major Qt release, the same does not hold for private API. However, simply removing private API in one module  can break other Qt modules which depend on it. While the submodule update bot workflow allows those modules to keep reusing a version of Qt that is still compatible with them, at some point they have to move to the latest version of their dependencies. Thus, any time one removes or modifies existing API, one should follow the procedure below to provide a smooth development experience for everyone working on Qt.
While public API cannot be removed outside of a new major Qt release, the same does not hold for private API. However, simply removing private API in one module  can break other Qt modules which depend on it. While the submodule update bot workflow allows those modules to keep reusing a version of Qt that is still compatible with them, at some point they have to move to the latest version of their dependencies. Thus, any time one removes or modifies existing API, one should follow the procedure below to provide a smooth development experience for everyone working on Qt.


; Check if your change breaks other modules: If you suspect that your change might break other modules, it is generally a good idea to at least compile the essential modules before merging your change. In the following steps, we assume that you actually found some breakage. Otherwise, you can just merge your change.
;Check if your change breaks other modules:If you suspect that your change might break other modules, it is generally a good idea to at least compile the essential modules before merging your change. In the following steps, we assume that you actually found some breakage. Otherwise, you can just merge your change.


; Preferred Workflows: If you can, try to split your change into two: One that adds the new API, and one that removes the old API. Then:
;Preferred Workflows:If you can, try to split your change into two: One that adds the new API, and one that removes the old API. Then:
# Merge the change which adds the new API
# Once a dependent module has been updated to use a SHA that has your change in, create a commit to port its usage of the old API to the new API.
# When all modules have been ported to the new API, integrate the change that removes the old API.


; Alternative Workflow: Sometimes, it is however not possible or very inconvenient to split your change into two atomic changes as described above. A common occurrence of this is when a bug fix necessitates a behavior change of existing API. In those cases, you can follow the following steps:  
#Merge the change which adds the new API
# Create commits to fix all modules and upload them to gerrit.
#Once a dependent module has been updated to use a SHA that has your change in, create a commit to port its usage of the old API to the new API.
# Ensure that they get reviewed and accepted, but do not stage them yet.
#When all modules have been ported to the new API, integrate the change that removes the old API.
# Integrate the breaking change.
 
# After the change has been integrated, add the submodule update bot as a reviewer to the changes in the other modules.
;Alternative Workflow:Sometimes, it is however not possible or very inconvenient to split your change into two atomic changes as described above. A common occurrence of this is when a bug fix necessitates a behavior change of existing API. In those cases, you can follow the following steps:
 
#Create commits to fix all modules and upload them to gerrit.
#Ensure that they get reviewed and accepted, but do not stage them yet.
#Integrate the breaking change.
#After the change has been integrated, add the submodule update bot as a reviewer to the changes in the other modules. Your changes will stage automatically with the next Submodule Update round.

Revision as of 07:20, 13 July 2022

While public API cannot be removed outside of a new major Qt release, the same does not hold for private API. However, simply removing private API in one module can break other Qt modules which depend on it. While the submodule update bot workflow allows those modules to keep reusing a version of Qt that is still compatible with them, at some point they have to move to the latest version of their dependencies. Thus, any time one removes or modifies existing API, one should follow the procedure below to provide a smooth development experience for everyone working on Qt.

Check if your change breaks other modules
If you suspect that your change might break other modules, it is generally a good idea to at least compile the essential modules before merging your change. In the following steps, we assume that you actually found some breakage. Otherwise, you can just merge your change.
Preferred Workflows
If you can, try to split your change into two: One that adds the new API, and one that removes the old API. Then:
  1. Merge the change which adds the new API
  2. Once a dependent module has been updated to use a SHA that has your change in, create a commit to port its usage of the old API to the new API.
  3. When all modules have been ported to the new API, integrate the change that removes the old API.
Alternative Workflow
Sometimes, it is however not possible or very inconvenient to split your change into two atomic changes as described above. A common occurrence of this is when a bug fix necessitates a behavior change of existing API. In those cases, you can follow the following steps:
  1. Create commits to fix all modules and upload them to gerrit.
  2. Ensure that they get reviewed and accepted, but do not stage them yet.
  3. Integrate the breaking change.
  4. After the change has been integrated, add the submodule update bot as a reviewer to the changes in the other modules. Your changes will stage automatically with the next Submodule Update round.