diff --git a/docs/how-to/index.md b/docs/how-to/index.md index ba070ef..e6f4d4a 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -11,6 +11,7 @@ kernel packages and components. Source code access and management Development and customization Test kernels in -proposed +Respin a kernel Contribute to kernel docs ``` @@ -36,3 +37,6 @@ These guides relate to testing the kernel to ensure its stability and functionality before you push or release a patch. - [Test kernels in -proposed](/how-to/testing-verification/test-kernel-in-proposed) + +## Respins +- [How to respin a kernel](/how-to/respin) diff --git a/docs/how-to/respin.md b/docs/how-to/respin.md new file mode 100644 index 0000000..3e43834 --- /dev/null +++ b/docs/how-to/respin.md @@ -0,0 +1,245 @@ +# How to respin a kernel + +Sometimes regressions or last-minute changes are identified in kernels in -proposed (already cranked). + +It is possible to make changes before the SRU cycle closes. This special version of a crank is called a respin. + +These are the steps to respin a kernel, with examples from a previous `2025.01.13` respin of the `noble:linux-gke` kernel due to a late-cycle decision to revert a patchset. + +## 1. Create a respin Jira card +The Jira card is used to keep track of the kernels that are being respun. + +```{attention} +Only one person peforms this step. If you already have a Jira card, note the respin number in the card (see Note at the end of this step) and skip this step. +``` + +Create a respin card on Jira using the [kteam-tools create-respin-card](https://kernel.ubuntu.com/forgejo/kernel/kteam-tools/src/branch/master/stable/create-respin-card) script. This Jira card will be . + +```text +./create-respin-card +``` + +For example, to respin a kernel for the "2025.01.13" SRU cycle: + +```text +./create-respin-card 2025.01.13 +``` + +Next, on Jira, fill in the details of the respin in the description. This can include: + +* Details on why the kernel is being respun +* Links to relevant bugs +* Affected kernels that will need to be respun + +```{note} +Note the respin number, as it's used in subsequent steps. + +The respin number is in the title of the Jira card in parentheses. +For example, "Re-spin (#8)" indicates the number is 8. +``` + +## 2. Create tracking bugs +Each affected kernel needs a new Launchpad tracking bug. + +Use the kteam-tools `create-kernel-tasks` script: + +```text +./create-kernel-tasks --handle --spin +``` + +For example, we used: +```{terminal} +:input: ./create-kernel-tasks --handle noble:linux-gke --spin 8 2025.01.13 +:dir: kteam-tools/stable/ +``` + +The output states that a new tracking bug has been made, prints its bug number, and also prints the bug number for the original tracking bug from this kernel's original crank. + +On Launchpad, mark the original tracking bug as a duplicate of the newly-created bug. + + +## 3. Checkout the last cranked version of the kernel + +Use cranky to checkout the kernel you want to respin: + +```text +cranky checkout --cleanup --pristine +``` + +Then, use `cranky rmadison` to get the version number from the -proposed kernel: +```text +cranky rmadison +``` +(If there are multiple entries for -proposed, use the one with the highest version number.) + +In `linux-main/`, ensure `HEAD` is on the tag of the kernel in -proposed (the output of `cranky rmadison`). + + + + + +## 4. Add patchset + +```{attention} +This step only applies to kernels which don't have a parent with patches applied. If your kernel has a parent kernel where respin patches were applied, skip this step. +``` + +Usually patches will come from a mailing list, as `.patch` files. Use `git am` to apply them. + +You may also be asked to modify the commit message. + + +## 5. Rebase +```{attention} +This step only applies to kernels which are derivatives of kernels also being respun. Skip this step if your kernel has a parent that isn't being respun. +``` + +Your kernel's parent will have a new tag from its respin. Rebase off that tag: +```text +cranky rebase -b +``` + +For `noble:linux-gke`, the parent kernel, `noble:linux`, was not respun, so we skipped this step. + +## 6. Continue cranking, with some modifications + +Run the following commands as normal: +```text +cranky open +cranky review-master-changes +``` + +Usually, no changes should be detected by this step. + +Next, run `cranky link-tb` with a modified cycle number: +```text +cranky link-tb --sru-cycle - +``` + +In our crank, we used `cranky link-tb --sru-cycle 2025.01.13-8`, where 8 was the spin number. + +Next, finish the crank: +```text +cranky update-dkms-versions +cranky close +cranky update-dependents +cranky tags +``` + +As always, be sure to double-check that the changes to the debian changelog in the closing commit look correct. + +## 7. Pull sources +The primary difference with pulling the previous deb package sources is that we need to specify to pull the ones in -proposed. (By default, `cranky pull-sources` pulls TODO.) + +First, we need to know which versions are in -proposed. Run `cranky rmadison` to get this info: +```text +cranky rmadison +``` + +You can `grep` the result for "proposed", too. + +Note both the package name `cranky rmadison` produces and the version numbers of each package this kernel has (main, meta, signed, etc.) that are in -proposed. + +For each package, we will run `cranky pull-source`. + +```{attention} +Note that the command is `cranky pull-source`, _not_ `cranky pull-sources` (no 's'). +We use `cranky pull-source` on each package manually so that we can specify the correct version number for each one. +``` + +Then, use `cranky pull-source` with the following syntax: +```text +cd .. +cranky pull-source +``` + +For example, the rmadison format looked like this (at time of our respin) for `noble:linux-gke` + +```{terminal} +:input: cranky rmadison noble:linux-gke +:dir: noble/linux-gke/ + + linux-gke | 6.8.0-1003.5 | noble | source + linux-gke | 6.8.0-1017.21 | noble-security | source + linux-gke | 6.8.0-1017.21 | noble-updates | source + linux-gke | 6.8.0-1019.23 | noble-proposed | source + linux-gke | 6.8.0-1017.21 | noble-proposed#2 | source + linux-meta-gke | 6.8.0-1003.5 | noble | source + linux-meta-gke | 6.8.0-1017.21 | noble-security | source + linux-meta-gke | 6.8.0-1017.21 | noble-updates | source + linux-meta-gke | 6.8.0-1019.23 | noble-proposed | source + linux-meta-gke | 6.8.0-1017.21 | noble-proposed#2 | source + linux-signed-gke | 6.8.0-1003.5 | noble | source + linux-signed-gke | 6.8.0-1017.21 | noble-security | source + linux-signed-gke | 6.8.0-1017.21 | noble-updates | source + linux-signed-gke | 6.8.0-1019.23 | noble-proposed | source + linux-signed-gke | 6.8.0-1017.21 | noble-proposed#2 | source +``` + +`noble:linux-gke` has `main`, `meta`, and `signed` packages, so we noted those specific package names and versions from `cranky rmadison`: + +| package name | version in `noble-updates` | +| - | - | +| `linux-gke` | `6.8.0-1017.21` | +| `linux-meta-gke` | `6.8.0-1017.21` | +| `linux-signed-gke` | `6.8.0-1017.21` | + +```{note} +In the example, the version numbers for each package are the same. +This is not always the case, so it's still important to go through this step for each package. +``` + +So, we ran the following commands: +```{terminal} +:input: cranky pull-source linux-gke 6.8.0-1017.21 noble +:dir: noble/linux-gke/ +``` + +```{terminal} +:input: cranky pull-source linux-meta-gke 6.8.0-1017.21 noble +:dir: noble/linux-gke/ +``` + +```{terminal} +:input: cranky pull-source linux-signed-gke 6.8.0-1017.21 noble +:dir: noble/linux-gke/ +``` + +## 8. Build sources + +We need to pass the information about the packages in -proposed gathered in the previous step (`pull-source`) to build the sources this time. + + +`cranky build-sources` has a `--build-opts` flag we can use to specify the version to use. Pass this flag once for each package, like so: + +```bash +cd linux-main/ +cranky build-sources --build-opts 'main:-v' --build-opts 'meta:-v' --build-opts 'signed:' +``` + +```{note} +The syntax used for each `--build-opts` is `:-v`. +The `package-dirname` is the name of the directory this package lives in (use `ls` to see them). +They are usually `linux-main/`, `linux-meta/`, `linux-lrm`, `linux-signed/`, etc. +Use these without the `linux-` prefix. +``` + +For example, we used the following command to build `noble:linux-gke`: + +```{terminal} +:input: cranky build-sources --build-opts 'main:-v6.8.0-1017.21' --build-opts 'meta:-v6.8.0-1017.21' --build-opts 'signed:-v6.8.0-1017.21' +:dir: noble/linux-gke/linux-main +``` + +## 9. Review changes and upload + +At this point, refer to the normal crank process to finish the respin. + +```bash +cd .. +cranky review *.changes +``` + +As always, double-check the generated `.debdiff` files look correct. + +Lastly, upload the package or push it for a peer-review.