Updating packages with API breaking changes

Read this ruby team's transitions primer if you are new to handling transitions.

Summary: Use experimental, see if things break, communicate if things are breaking, ask for help and together fix the breakages.

Longer version: At least https://SemVer.org compliance should be assumed as a compromise (as assuming every change breaks is not practical). This means major version updates of upstream with public API (when version >= 1.0) and minor updates of upstream without a public API (when version < 1.0). For example rollup update from 0.8 to 1.0 and browserify-lite update from 0.5 to 0.6, both are breaking changes (sometimes we may be lucky and nothing breaks, but we cannot assume that when upstream explicitly gives a warning by appropriate version bumps).

When uploading such API breaking changes these steps must be followed,

  1. Verify autopkgtests of all reverse dependencies and rebuilds of all reverse build dependencies are passing. Use one of the two options listed below
    1. For both autopkgtests and rebuilds, use Packaging/ruby-team-meta-build

    2. For autopkgtests, upload to experimental and follow britney pseudo-excuses for experimental. For rebuilds, request archive rebuilds as a service.

  2. There are two paths you can take for uploading to unstable,
    1. Ideally all breaking packages should be fixed before uploading to unstable. Fixed packages should be uploaded along with the package that introduced API breakage.
    2. Upload to experimental and file bug reports with severity important against all failed packages. It is a good idea to document the list of packages that failed in debian/changelog. Give sufficient time for the maintainers (at least a week for simple fixes or more for complex changes) to fix the broken packages.
  3. When all the broken packages are fixed or the provided time is passed, upload to unstable along with all the fixed packages. Add Breaks for all the packages that failed. The bugs against unfixed packages should be raised to serious.

Note 1: Bigger transitions like nodejs or babel may need collaboration from the whole team and new versions may be uploaded to unstable and broken packages may be fixed later. Try to coordinate with the team on the mailing list.

Note 2: It is recommended to forward such patches to upstream. See Javascript/Transitions/ForwardingChangesUpstream for how to prepare merge requests for upstream.