From 596a5b347c1d914c212b6c0937e6e0c9150dfc12 Mon Sep 17 00:00:00 2001 From: Piyush Jena Date: Tue, 3 Mar 2026 00:17:55 +0000 Subject: [PATCH 1/3] fix(README): update installation path for forester implementation Signed-off-by: Piyush Jena --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 04ba480d..4104ab02 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ Generic forest management tool. Install via: ```bash -cargo install forester +cargo install --path ./crates/forester ``` Usage: From d92f87d4da7bca0046cabf4133b0b44c64ed7291 Mon Sep 17 00:00:00 2001 From: Piyush Jena Date: Tue, 3 Mar 2026 00:18:41 +0000 Subject: [PATCH 2/3] skills: add skill to build individual packages in the kits Signed-off-by: Piyush Jena --- skills/build-package/SKILL.md | 81 +++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 skills/build-package/SKILL.md diff --git a/skills/build-package/SKILL.md b/skills/build-package/SKILL.md new file mode 100644 index 00000000..11a07df4 --- /dev/null +++ b/skills/build-package/SKILL.md @@ -0,0 +1,81 @@ +--- +name: build-package +description: Build a third party package in a Bottlerocket kit (core-kit or kernel-kit) +--- + +# Skill: Build and Publish Kit + +## Purpose + +Build a third party package in a Bottlerocket kit (core-kit or kernel-kit). This allows you to test changes in a third party package spec file or Cargo.toml without publishing to production registries. You can use it while updating or modifying a package. + +## When to Use + +- After modifying a package spec +- After updating a package version +- Debugging a package build failure +- Iterating on patches or spec file changes + +## Prerequisites + +- Docker installed and running +- Working from within a grove directory +- Kit repository cloned in `kits/` directory (e.g., `kits/bottlerocket-core-kit`) + +## Input + +The user provides: +- **Package name** (e.g. `libselinux`) +- **Kit name** (e.g. `bottlerocket-core-kit`) + +## Procedure + +### 1. Locate the package + +```bash +ls kits//packages// +``` + +Some packages are versioned (e.g., `kubernetes-1.29`, `ecr-credential-provider-1.30`). +If the user specifies a versioned package, locate the correct directory. + +### 2. Navigate to the kit + +```bash +cd kits/ +``` + +### 3. Build the package + +```bash +PACKAGE= make twoliter build-package +``` + +## Common Issues + +**Format error** +``` +error: invalid character `.` in package name: +``` +Solution: Replace `.` with `_` in package name and retry. + +**Package is not present in bottlerocket cache:** +``` +Failed to fetch `https://cache.bottlerocket.aws +``` +Solution: Run the following +```bash +PACKAGE= make twoliter build-package -e BUILDSYS_UPSTREAM_SOURCE_FALLBACK=true +``` + +**Build takes too long:** +Single-package builds are much faster than full kit builds, but some packages (e.g., kernel) are inherently slow. + +**Dependency not yet built:** +If the package depends on another package that hasn't been built yet, you may need to build the dependency first or do a full kit build. + +**Twoliter not found:** +Ensure you're in the kit directory and the Makefile/twoliter is properly configured. + +**Docker permission denied:** +Solution: Ensure user is in docker group and Docker daemon is running From 73f4cd91f51dd282215f5bf3d2e23bd46fe75154 Mon Sep 17 00:00:00 2001 From: Piyush Jena Date: Mon, 23 Mar 2026 21:10:17 +0000 Subject: [PATCH 3/3] skills: add skill to update packages in the kits Signed-off-by: Piyush Jena --- skills/update-package/SKILL.md | 227 +++++++++++++++++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 skills/update-package/SKILL.md diff --git a/skills/update-package/SKILL.md b/skills/update-package/SKILL.md new file mode 100644 index 00000000..cde70c3b --- /dev/null +++ b/skills/update-package/SKILL.md @@ -0,0 +1,227 @@ +--- +name: update-package +description: Update a third-party package to a new version in Bottlerocket kit (core-kit or kernel-kit) +--- + +# Skill: Update Third Party Package + +## Purpose + +Update a package to a new upstream version within a Bottlerocket kit (core-kit or kernel-kit). This includes updating the the Cargo.toml - source URL and hash, if present the signature's source URL and hash, the RPM spec file, and re-applying or re-creating patches as needed. + +## When to Use + +- Updating a third-party package to a new upstream release + +## Prerequisites + +- Working from within a grove directory +- Kit repository cloned in `kits/` directory (e.g., `kits/bottlerocket-core-kit`) + +## Input + +The user provides: +- **Package name(s) and the version to update to** (e.g., `libselinux=3.7` or `libselinux=3.7 libsepol=3.7`) +- **Kit name** (e.g. `bottlerocket-core-kit`) + +## Procedure + +### 1. Locate the package + +```bash +ls kits//packages// +``` + +Some packages are versioned (e.g., `kubernetes-1.29`, `ecr-credential-provider-1.30`). +If the user specifies a versioned package, locate the correct directory. + +Identify the key files: +- `Cargo.toml` — source URL(s) and SHA-512 hashes for the package and if present the signatures +- `.spec` — RPM spec with Version, Release, %prep, %build, %install, %changelog +- `*.patch` — any existing patches + +Read all of them before making changes. + +### 2. Navigate to the kit + +```bash +cd kits/ +``` + +### 3. Update Cargo.toml + +Open `packages//Cargo.toml`. + +Use the url field in `[[package.metadata.build-package.external-files]]` sections and replace the version to point to the new version. The URL pattern varies by package — match the existing pattern but replace the old version with the new one. + +If there is a `path` field in the same section (overrides the downloaded filename), update the version in it too. + +To get the new hash, download the source and compute it: + +```bash +TMPDIR=$(mktemp -d) +curl -L -o "$TMPDIR/source.tar.gz" "" +sha512sum "$TMPDIR/source.tar.gz" | awk '{print $1}' +rm -rf "$TMPDIR" +``` + +If there are multiple `[[package.metadata.build-package.external-files]]` entries (e.g., separate source tarballs, signature files), update each one that embeds the version. + +The `releases-url` field at the top of the build-package metadata section points to the upstream release page — use it to verify the new version exists and find the correct download URL if the pattern isn't obvious. + +In some cases, patch files have to be appended. Follow the format of the Cargo.toml to add new patch files from the upstream source. + +#### Kubernetes packages + +In case of kubernetes packages, the URL contains both the release number (eg. `releases/12/`) and the kubernetes version (eg. `v1.34.3`). Release version is usually the one that's provided. To find the correct patch number, check the EKS distro releases page or try incrementing the patch number until the URL resolves. + +### 3. Update the spec file + +Open `packages//.spec`. + +**Read the spec file carefully first** to identify which versioning pattern it uses. +Different packages use different macro patterns — you must match the existing pattern. + +Update these fields: +- `Version:` — set to the new version (unless a macro derives it — see below) +- `Release:` — reset to `1%{?dist}` (unless it uses a special pattern like `%{ncurses_rev}%{?dist}`) +- `Source{xx}:` (Source lines) — update filenames if they embed the version or a file was replaced by a new one (eg. GPG key) + +DO NOT CHANGE THE `Epoch:` field if present. + +#### Spec versioning patterns + +Packages use various macro patterns for versioning. Always check which pattern the spec uses: + +- **Direct `Version:`** — most common. Just update the `Version:` field. +- **`%global gover`** — Go packages. Update `gover`, leave `Version:` alone. +- **`%global unversion`** — libexpat style. Uses underscores (e.g., `2_7_2`). Update with underscored new version. `Version:` is derived via sed. +- **`%global ncurses_rev`** — libncurses. The date portion (e.g., `20250927`). `Version:` stays as the major version. `Release:` uses `%{ncurses_rev}%{?dist}` — do not reset it. +- **`%global releasever`** — kubernetes. The EKS release number. See Kubernetes section below. +- **`%global majorminor` + `%global version`** — util-linux style. `majorminor` is like `2.41`, `version` is like `%{majorminor}.2`. Update the patch number in `%global version`. + +Note: Some packages use a different version format in the spec `Version:` field than in the URL. +For example, libinih uses `Version: 60` in the spec but `r60` in the URL. +When updating, ensure both the spec version and the URL version are updated consistently with their respective formats. + +#### Kubernetes packages + +The spec has these 2 global variables `gover`, `releasever` defined as follows: +```spec +%global releasever +%global gover +``` +Just change the value of the `releasever` variable and if you had to bump the patch version while updating `Cargo.toml` then `gover` instead of `Version:` field in this case. If the Source references the global variable `gover` then no need to change. + +#### Other Go packages + +The spec may have a global variable `gover` defined as follows: +```spec +%global gover NEW_VERSION +``` +Just change the value of this variable instead of `Version:` field in this case. If the Source references the global variable `gover` then no need to change. + +Check whether the upstream bumped its Go version. +If so, update the `GO_MAJOR` export in the `%build` section of the spec: + +```spec +export GO_MAJOR="1.25" +``` + +Only set this if the upstream project actually requires the newer Go version. +If the build system's default Go version now matches or exceeds what upstream requires, **remove** the `GO_MAJOR` export line (and any trailing blank line after it) instead of updating it. + +#### Packages with incremental patches + +Some packages (e.g., readline) release incremental patches rather than full tarballs for minor updates. +These patches are available from the upstream distribution site (e.g., `https://ftp.gnu.org/gnu/readline/readline-8.3-patches/`). +Match the existing Cargo.toml pattern for how these are pulled in. If a new set of patches are added, make sure a .gitignore file is also +added so that those patches don't show up as uncommitted. And do not commit those patches. + +### 4. Build the package + +Use SKILL `build-package` to build `` in ``. +In case of multiple packages build them one by one. + +## Validation + +After making all changes, verify: +- [ ] `Cargo.toml` has correct URL(s) and valid SHA-512 hash(es) +- [ ] Spec file `Version:` matches the new version +- [ ] Spec file `Release:` is reset to `1%{?dist}` +- [ ] All `Source` lines reference correct filenames +- [ ] Patches are either removed (if upstreamed) or kept with correct numbering +- [ ] No stale patch references remain in the spec +- [ ] GPG keys are current if upstream rotated signing keys +- [ ] Package successfully builds using `build-package` skill + +## Commit Messages + +If the Validation passes then create the commit. +Follow the project convention: `packages: update to ` + +Note removed patches in the commit body (e.g., "removed upstreamed patch for X"). + +``` +packages: update nvidia-k8s-device-plugin to v0.18.0 + +Signed-off-by: Your Name +``` + +## Common Issues + +**Signing Verification failed during package build:** +``` +gpgverify: Decoding the keyring failed. +``` +Solution: The GPG key used for signature verification has been rotated by the upstream project. + +1. Find the key ID used to sign the new release (check the `.asc`/`.sig` file or upstream release notes) +2. Download the new public key from a keyserver or the upstream project +3. Save it as `gpgkey-.asc` in the package directory +4. Delete the old `gpgkey-*.asc` file +5. Update the `Source{xx}:` line in the spec to reference the new key filename +6. Update the Cargo.toml if the key file is listed as an external-file + +**Missing Dependency:** + +Check if the new version has changed build requirements. +If so, update `BuildRequires:` in the spec file and any path dependencies in `Cargo.toml`: + +```toml +[build-dependencies] +some-other-package = { path = "../some-other-package" } +``` + +This also requires update to `sources/Cargo.lock`. To do that just run `cargo build` inside `sources` directory. + +**Patch application failure:** +For the problematic patch: +1. Read the patch to understand what it modifies +2. Determine if the fix has been upstreamed in the new version: + - If upstreamed: remove the patch file and its `PatchNNNN:` and `%patch` lines from the spec + - If still needed: keep it, but note it may need rebasing + - If uncertain: keep it for now — the build step will reveal if it applies cleanly + +To check if a patch was upstreamed, look at the upstream changelog or release notes for the new version. +If the patch was originally created from an upstream commit (check the `From` header in the patch), search for that commit in the new release. + +If rebase is required for the patch, then prefer `git format-patch` from the upstream repo to preserve the original commit reference: + +```bash +git clone +cd +git format-patch -1 +``` + +This keeps provenance and makes review easier. + +Use standard `git format-patch` style numbering (0001-, 0002-, etc.) and add corresponding `PatchNNNN:` and `%patch -P NNNN -p1` lines in the spec. + +If a new version introduces behavior that needs a Bottlerocket-specific fix, document why the patch is needed in the commit message using cite-style links: + +``` +as suggested in [1] + +[1]: https://example.com/relevant-issue +```