From 3125b646be52f43a1db3b85b5129a703ed3628f9 Mon Sep 17 00:00:00 2001 From: NomadicCore Date: Sat, 24 Jan 2026 22:32:42 +0000 Subject: [PATCH 1/4] NewRecipe: Draft page from CookieSource for creating a new recipe CookieSource created a draft page for creating a new recipe. Uploading as a draft so we can colaboratively refine To-Do: - Check structure and language against "Updating an existing package recipe" - Answer comments and questions raised - Remove drafting notes --- .../Workflow/creating-a-new-recipe.mdx | 263 +++++++++++++++++- 1 file changed, 261 insertions(+), 2 deletions(-) diff --git a/src/content/docs/Packaging/Workflow/creating-a-new-recipe.mdx b/src/content/docs/Packaging/Workflow/creating-a-new-recipe.mdx index 06a4fa70..7ba860bd 100644 --- a/src/content/docs/Packaging/Workflow/creating-a-new-recipe.mdx +++ b/src/content/docs/Packaging/Workflow/creating-a-new-recipe.mdx @@ -1,6 +1,265 @@ --- title: 'Creating a new package recipe' -lastUpdated: 2025-01-10T02:48:02+01:00 +lastUpdated: 2026-01-24T22:15:00+01:00 --- -(TBD) + + +This guide walks through gathering upstream information and filling in each field of a new recipe. We will use GNU Nano as the running example, but the same steps apply to any new package. + +## Prepare your workspace + +The guide assumes you have followed the [prerequisites](/packaging/workflow/prerequisites/) checklist and [Basic Packaging Workflow](/packaging/workflow/basic-workflow/). If you have not done this, please follow those steps first before proceeding. Ensure you have updated your local clone of the AerynOS repository on your own system before proceeding any further. + +As a reminder, you want to ensure you have the volatile repository enabled and fully updated on your system. + +For a recap, if you have followed the previous guides, the commands will be: + +```bash +sudo moss repo enable volatile +sudo moss sync -u +gotoaosrepo +git switch main +gh repo sync yourusername/yourfork -b main +git pull +``` + +Change `yourusername` to your github username and `yourfork` to the name you selected for your fork of the AerynOS repository. By default the fork is called `recipes`. + +## Create a feature branch + +When conducting any packaging work, it is a good idea to separate out your work in a different branch. This allows you to isolate changes you make from one package in a separate branch to changes you make to a different package in a second branch and so on. This additionally is helpful as it keeps your work separate to any underlaying changes made to the `main` recipes repository, more easily allowing you to rebase your work if needed. + +```bash +git checkout -b add_packagename +``` + +Change "add_packagename" to whatever description you feel comfortable with. + +You can check what branch you are on and what branches you have in your repository with the following command: + +```bash +git branch -a +``` + +## Scaffold the recipe directory + +Moss and Boulder do not generate skeleton recipes. Create the directory structure yourself and drop in a minimal `stone.yaml`. + +_// `boulder recipe new` actually generates a skeleton recipe -- have you tried it? Please try invoking `boulder recipe new --help` //_ + +1. Pick the correct first-letter directory (`n/nano`, `p/python-click`, etc.). +2. Create the path and enter it. + +```bash +mkdir -p n/nano +cd n/nano +``` + +### Minimal stone.yaml skeleton + +Copy in this template and replace the placeholders. + +```yaml +name : example +version : "1.0.0" +release : 1 +homepage : https://example.org +upstreams : + - https://example.org/example-1.0.0.tar.xz : +summary : Short explanation +description : | + One or two sentences that explain what the package delivers. +license : + - +builddeps : [] +setup : | + # replace with %configure, %meson, etc. +build : | + # replace with %make, %meson_build, etc. +install : | + # replace with %make_install, %meson_install, etc. +``` + +_// IIRC, `boulder recipe new` also tries to set up monitoring.yaml for us... :thinking_face: //_ + +Add a matching `monitoring.yaml` with placeholder fields so release tracking can be wired up later. + +```yaml +releases: + id: ~ + rss: ~ +security: + cpe: ~ +``` + +## Fill the recipe step by step + +The rest of this guide shows how to replace each placeholder by pulling information from upstream Nano. + +### Step 1 · Collect upstream metadata + +- Search for “GNU Nano download” to locate the upstream homepage: https://www.nano-editor.org/. +- Note the latest release number (`8.6` at the time of writing) and the canonical download link. +- Record any prerequisites listed in upstream build instructions—these become candidates for `builddeps` later. + +The Nano "bleeding edge" page lists the following tools you should keep in mind: + +| Package | Minimum Version | +|--------------|-----------------| +| autoconf | 2.69 | +| automake | 1.14 | +| autopoint | 0.20 | +| gcc | 5.0 | +| gettext | 0.20 | +| git | 2.7.4 | +| groff | 1.12 | +| make | (any version) | +| pkg-config | 0.22 | +| texinfo | 4.0 | + +### Step 2 · Add core metadata fields + +Fill in the obvious fields first: `name`, `version`, `release`, `homepage`, and a short `summary`. + +```yaml +name : nano +version : "8.6" +release : 1 +homepage : https://www.nano-editor.org/ +summary : GNU Text Editor +description : | + Nano is a small and simple text editor for the terminal. +``` + +Tip: keep `release` at `1` when you introduce a brand-new package. Bump it only when you make changes to the recipe after it lands and you don't update the version on version updates we go back to release 1. + +### Step 3 · Wire up the source tarball and checksum + +1. Copy the download URL from the upstream releases page (for Nano: `https://www.nano-editor.org/dist/v8/nano-8.6.tar.xz`). +2. Download it locally and compute its SHA-256 checksum: + + ```bash + curl -L -o nano-8.6.tar.xz https://www.nano-editor.org/dist/v8/nano-8.6.tar.xz + sha256sum nano-8.6.tar.xz + ``` + +3. Place the URL and checksum into the `upstreams` section, then remove the temporary tarball. + +```yaml +upstreams : + - https://www.nano-editor.org/dist/v8/nano-8.6.tar.xz : f7abfbf0eed5f573ab51bd77a458f32d82f9859c55e9689f819d96fe1437a619 +``` + +### Step 4 · Capture a meaningful description + +Pull a concise paragraph from upstream documentation or write one that explains what the package provides. Wrap at ~80 characters to keep reviews readable. Multi-line strings belong under the `description` block using the `|` YAML literal syntax. + +```yaml +description : | + Nano is a small and simple text editor for use on the terminal. + It mirrors Pico's interface but adds undo/redo, syntax highlighting, + line numbers, soft wrapping, multiple buffers, and search/replace + with regular expressions. +``` + +### Step 5 · Declare the license + +Find the license in upstream’s repository (often `COPYING`, `LICENSE`, or package metadata). Convert it to an SPDX identifier—Nano uses `GPL-3.0-or-later`. + +```yaml +license : + - GPL-3.0-or-later +``` + +### Step 6 · Translate prerequisites into build dependencies + +Map each upstream requirement to the package name that exists in AerynOS. Use `pkg-config()` helpers when libraries provide `.pc` files. Toolchain components like `gcc` and `make` are already available inside the build environment, so you do not have to list them. + +| Upstream prerequisite | Recipe build dependency | +|-----------------------|-----------------------------------| +| `ncurses` | `pkgconfig(ncursesw)` | +| `zlib` | `pkgconfig(zlib)` | +| `libmagic` | `pkgconfig(libmagic)` | +| `autoconf`, `automake`| already provided by the sandbox | + +Add them to `builddeps`: + +```yaml +builddeps : + - pkgconfig(libmagic) + - pkgconfig(ncursesw) + - pkgconfig(zlib) +``` + +### Step 7 · Fill in build steps + +Nano follows the GNU autotools flow, so use the standard macros (`%configure`, `%make`, `%make_install`). Consult the macro documentation for variations: https://aerynos.dev/packaging/macros/autotools/ . + +```yaml +setup : | + %configure +build : | + %make +install : | + %make_install +``` + +### Step 8 · Review the finished recipe + +Combining all of the steps gives you a complete `stone.yaml`: + +```yaml +name : nano +version : "8.6" +release : 1 +homepage : https://www.nano-editor.org/ +upstreams : + - https://www.nano-editor.org/dist/v8/nano-8.6.tar.xz : f7abfbf0eed5f573ab51bd77a458f32d82f9859c55e9689f819d96fe1437a619 +summary : GNU Text Editor +description : | + Nano is a small and simple text editor for use on the terminal. + It mirrors Pico's interface but adds undo/redo, syntax highlighting, + line numbers, soft wrapping, multiple buffers, and search/replace + with regular expressions. +license : + - GPL-3.0-or-later +builddeps : + - pkgconfig(libmagic) + - pkgconfig(ncursesw) + - pkgconfig(zlib) +setup : | + %configure +build : | + %make +install : | + %make_install +``` + +Adjust any values that differ for your package (version numbers, dependencies, macros, etc.) before moving on. + +## Add monitoring metadata + +Release monitoring keeps automated eyes on your package. Update `monitoring.yaml` once you know the upstream identifiers: + +1. Search for the project on https://release-monitoring.org/ and copy the numeric `id`. +2. Add an RSS or Atom feed URL if upstream publishes one; otherwise leave `rss: ~`. +3. Check the National Vulnerability Database for a CPE string (https://nvd.nist.gov/products/cpe/search). If none exists, leave it as `~`. + +```yaml +releases: + id: 2046 # Release Monitoring ID for nano + rss: ~ # Replace when upstream publishes a feed +security: + cpe: cpe:2.3:a:gnu:nano:*:*:*:*:*:*:*:* # Update if upstream changes identifiers +``` + +## Build and test + +From the recipe directory, run: + +```bash +just build +``` + +This executes `boulder build …` with your `stone.yaml`. If the build fails, adjust the recipe, repeat the relevant step above, and rebuild until it succeeds. Finish by committing the new package on your feature branch and opening a pull request. From 1fa45605110255cddaaabb8617e3ae936060f98f Mon Sep 17 00:00:00 2001 From: NomadicCore Date: Sun, 25 Jan 2026 14:25:00 +0000 Subject: [PATCH 2/4] Packaging Workflow: Complete review of packaging section Updated the complete packaging workflow with the addition of a new "Creating a new package recipe" page and then splitting out additional copy into separate pages so copy isn't duplicated across Creating and Updating package recipe pages - New "Preparing for packaging" page - New "Creating a new package recipe" page - New "Building and testing packages" page - New "Checking for package updates" page - Updated "Updating a package recipe" page **Testing** - Built dotdev locally and ensured site was wroking, particularly given the new pages added --- astro.config.mjs | 3 + .../Packaging/Workflow/basic-workflow.mdx | 2 +- .../building-and-testing-packages.mdx | 54 +++ .../Workflow/checking-for-updates.mdx | 48 +++ .../Workflow/creating-a-new-recipe.mdx | 335 +++++++++++------- src/content/docs/Packaging/Workflow/index.mdx | 2 +- .../Workflow/preparing-for-packaging.mdx | 40 +++ .../Packaging/Workflow/submitting-a-pr.mdx | 2 +- .../Workflow/updating-an-existing-recipe.mdx | 140 +------- 9 files changed, 365 insertions(+), 261 deletions(-) create mode 100644 src/content/docs/Packaging/Workflow/building-and-testing-packages.mdx create mode 100644 src/content/docs/Packaging/Workflow/checking-for-updates.mdx create mode 100644 src/content/docs/Packaging/Workflow/preparing-for-packaging.mdx diff --git a/astro.config.mjs b/astro.config.mjs index 7324ca7f..38efea76 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -144,9 +144,12 @@ export default defineConfig({ { slug: "packaging/workflow" }, { slug: "packaging/workflow/prerequisites" }, { slug: "packaging/workflow/basic-workflow" }, + { slug: "packaging/workflow/preparing-for-packaging" }, { slug: "packaging/workflow/creating-a-new-recipe" }, { slug: "packaging/workflow/updating-an-existing-recipe" }, + { slug: "packaging/workflow/building-and-testing-packages" }, { slug: "packaging/workflow/submitting-a-pr" }, + { slug: "packaging/workflow/checking-for-updates" }, ], }, { diff --git a/src/content/docs/Packaging/Workflow/basic-workflow.mdx b/src/content/docs/Packaging/Workflow/basic-workflow.mdx index 433bc873..88c38aff 100644 --- a/src/content/docs/Packaging/Workflow/basic-workflow.mdx +++ b/src/content/docs/Packaging/Workflow/basic-workflow.mdx @@ -1,5 +1,5 @@ --- -title: 'Basic Packaging Workflow' +title: 'Basic packaging workflow' lastUpdated: 2025-06-23T00:00:00Z description: "Building packages locally and testing them" --- diff --git a/src/content/docs/Packaging/Workflow/building-and-testing-packages.mdx b/src/content/docs/Packaging/Workflow/building-and-testing-packages.mdx new file mode 100644 index 00000000..e55bd6d3 --- /dev/null +++ b/src/content/docs/Packaging/Workflow/building-and-testing-packages.mdx @@ -0,0 +1,54 @@ +--- +title : 'Building and testing packages' +lastUpdated: 2026-01-25T12:00:00+00:00 +description: "How to build and test packages locally on your system" +--- +import { Aside } from '@astrojs/starlight/components'; + + +This guide will walk you through the process of building and testing packages locally on your system, regardless of whether they come from new package recipes or existing ones you are updating. + +## Build the package + +Once you have created or updated a package recipe, you will need to build it locally. If you are only updating one package, you can either keep your local repository disabled prior to building the package. If you prefer to keep it enabled, make sure there are no other packages indexed locally that could interfere with your new package build. + + + + +The command to build the updated package is: + +```bash +just build +``` + +If the package is successfully built, you will need to move it to your local repository. You can do this using the following command: + +```bash +just mv-local +``` + +If you have not yet enabled the local repository, you do this with the following command: + +```bash +sudo moss repo enable local +``` + +You will then need to sync the local repository using the command: + +```bash +sudo moss sync -u +``` + +Note, if you already have an older version of the package installed, you will be asked if you want to update to the new local version you have just built. If you have not yet installed this package, you would install it as normal using the command: + +```bash +sudo moss install "package name" +``` + +Once you have tested the package, you can make a submission for including the update in the repository. + + diff --git a/src/content/docs/Packaging/Workflow/checking-for-updates.mdx b/src/content/docs/Packaging/Workflow/checking-for-updates.mdx new file mode 100644 index 00000000..75244e1a --- /dev/null +++ b/src/content/docs/Packaging/Workflow/checking-for-updates.mdx @@ -0,0 +1,48 @@ +--- +title : 'Checking for package updates' +lastUpdated: 2026-01-25T12:00:00+00:00 +description: "How to check for package updates" +--- +import { Aside } from '@astrojs/starlight/components'; + + +## Use `ent` to check for package updates + +This guide will walk you through the process using `ent`, a tool built by the AerynOS team to check for package updates. `ent` checks recipes against upstream sources to determine whether updates are available. + +`ent` is not installed on your system by default. To install `ent` using `moss`, use the following command: + +```bash +sudo moss install ent +``` +### How `ent` works + +`ent` scans the current directory and all subdirectories beneath it. It inspects each recipe `monitoring.yaml` file and compares the referenced `stone.yaml` recipe upstreams to determine whether newer versions are available. + +Because `ent` operates relative to the directory in which it is executed, you can control the scope of the update check by choosing where to run the command within the recipes repository. + +### Running update checks + +To check for updates across all recipes, run the following command from the root of the recipes repository: + +```bash +gotoaosrepo +ent check updates +``` + +You can also run this command from more specific locations: + +* **Repository root** + Checks all recipes in the repository. + +* **Letter directory (for example, `f/`)** + Checks only recipes whose names start with that letter. + +* **Specific recipe directory (for example, `f/firefox/`)** + Checks only that single recipe. + +For example, running the command from `f/firefox/` will check only the Firefox recipe for available updates. + + diff --git a/src/content/docs/Packaging/Workflow/creating-a-new-recipe.mdx b/src/content/docs/Packaging/Workflow/creating-a-new-recipe.mdx index 7ba860bd..04d5082a 100644 --- a/src/content/docs/Packaging/Workflow/creating-a-new-recipe.mdx +++ b/src/content/docs/Packaging/Workflow/creating-a-new-recipe.mdx @@ -1,106 +1,39 @@ --- title: 'Creating a new package recipe' -lastUpdated: 2026-01-24T22:15:00+01:00 +lastUpdated: 2026-01-25T12:00:00+00:00 +description: "Creating a new package recipe from scratch" --- +import { Aside } from '@astrojs/starlight/components'; +This guide details the process of creating a new package recipe that is not yet present in the [AerynOS repository](https://github.com/AerynOS/recipes). We will use Nano as the running example, but the same steps apply to any new package. -This guide walks through gathering upstream information and filling in each field of a new recipe. We will use GNU Nano as the running example, but the same steps apply to any new package. +Before creating the package recipe yourself, please double check that there isn't already an outstanding PR for the package you want to include. Please also check if someone has created a new package request issue in the [AerynOS recipes repository](https://github.com/AerynOS/recipes). ## Prepare your workspace -The guide assumes you have followed the [prerequisites](/packaging/workflow/prerequisites/) checklist and [Basic Packaging Workflow](/packaging/workflow/basic-workflow/). If you have not done this, please follow those steps first before proceeding. Ensure you have updated your local clone of the AerynOS repository on your own system before proceeding any further. +Prior to starting, ensure you have followed the [prerequisites](/packaging/workflow/prerequisites/) set up process, the [Basic Packaging Workflow](/packaging/workflow/basic-workflow/) and updated your system in accordance with [Preparing for Packaging](/packaging/workflow/preparing-for-packaging/) guide. -As a reminder, you want to ensure you have the volatile repository enabled and fully updated on your system. - -For a recap, if you have followed the previous guides, the commands will be: - -```bash -sudo moss repo enable volatile -sudo moss sync -u -gotoaosrepo -git switch main -gh repo sync yourusername/yourfork -b main -git pull -``` - -Change `yourusername` to your github username and `yourfork` to the name you selected for your fork of the AerynOS repository. By default the fork is called `recipes`. - -## Create a feature branch - -When conducting any packaging work, it is a good idea to separate out your work in a different branch. This allows you to isolate changes you make from one package in a separate branch to changes you make to a different package in a second branch and so on. This additionally is helpful as it keeps your work separate to any underlaying changes made to the `main` recipes repository, more easily allowing you to rebase your work if needed. - -```bash -git checkout -b add_packagename -``` - -Change "add_packagename" to whatever description you feel comfortable with. - -You can check what branch you are on and what branches you have in your repository with the following command: - -```bash -git branch -a -``` +If you have not done this, follow those steps first before proceeding. ## Scaffold the recipe directory -Moss and Boulder do not generate skeleton recipes. Create the directory structure yourself and drop in a minimal `stone.yaml`. - -_// `boulder recipe new` actually generates a skeleton recipe -- have you tried it? Please try invoking `boulder recipe new --help` //_ - -1. Pick the correct first-letter directory (`n/nano`, `p/python-click`, etc.). -2. Create the path and enter it. +Prior to starting, you need to create the directory structure for your recipe. In our example, we will create a recipe for the Nano text editor. Each recipe is stored in its own directory within the recipes repository you already have downloaded to your computer. In this case, we will create a directory called `nano` in the `n` directory: ```bash +gotoaosrepo mkdir -p n/nano cd n/nano ``` -### Minimal stone.yaml skeleton - -Copy in this template and replace the placeholders. - -```yaml -name : example -version : "1.0.0" -release : 1 -homepage : https://example.org -upstreams : - - https://example.org/example-1.0.0.tar.xz : -summary : Short explanation -description : | - One or two sentences that explain what the package delivers. -license : - - -builddeps : [] -setup : | - # replace with %configure, %meson, etc. -build : | - # replace with %make, %meson_build, etc. -install : | - # replace with %make_install, %meson_install, etc. -``` - -_// IIRC, `boulder recipe new` also tries to set up monitoring.yaml for us... :thinking_face: //_ - -Add a matching `monitoring.yaml` with placeholder fields so release tracking can be wired up later. - -```yaml -releases: - id: ~ - rss: ~ -security: - cpe: ~ -``` - ## Fill the recipe step by step -The rest of this guide shows how to replace each placeholder by pulling information from upstream Nano. +The rest of this guide shows how to create a recipe and to replace any missing metadata by pulling information from upstream Nano. -### Step 1 · Collect upstream metadata + ### Step 1 - Collect upstream metadata - Search for “GNU Nano download” to locate the upstream homepage: https://www.nano-editor.org/. -- Note the latest release number (`8.6` at the time of writing) and the canonical download link. +- Note the latest release number (`8.7` at the time of writing) and the canonical download link. - Record any prerequisites listed in upstream build instructions—these become candidates for `builddeps` later. The Nano "bleeding edge" page lists the following tools you should keep in mind: @@ -118,61 +51,110 @@ The Nano "bleeding edge" page lists the following tools you should keep in mind: | pkg-config | 0.22 | | texinfo | 4.0 | -### Step 2 · Add core metadata fields +### Step 1 - Use `boulder` to help create the recipe -Fill in the obvious fields first: `name`, `version`, `release`, `homepage`, and a short `summary`. +We use `boulder` to help create the recipe using the `boulder recipe new` command. This command will generate a skeleton recipe for you to fill in. `boulder` will read the contents of the source code of the package you are trying to add and automatically create a `stone.yaml` recipe file and a `monitoring.yaml` file. -```yaml -name : nano -version : "8.6" -release : 1 -homepage : https://www.nano-editor.org/ -summary : GNU Text Editor -description : | - Nano is a small and simple text editor for the terminal. +```bash +boulder recipe update "upstream URL" ``` -Tip: keep `release` at `1` when you introduce a brand-new package. Bump it only when you make changes to the recipe after it lands and you don't update the version on version updates we go back to release 1. +In the example of Nano, to create a recipe based on version 8.7, you would use the following command: -### Step 3 · Wire up the source tarball and checksum +```bash +boulder recipe new https://www.nano-editor.org/dist/v8/nano-8.7.tar.xz +``` -1. Copy the download URL from the upstream releases page (for Nano: `https://www.nano-editor.org/dist/v8/nano-8.6.tar.xz`). -2. Download it locally and compute its SHA-256 checksum: +This command does the following: - ```bash - curl -L -o nano-8.6.tar.xz https://www.nano-editor.org/dist/v8/nano-8.6.tar.xz - sha256sum nano-8.6.tar.xz - ``` +1) Creates a new `stone.yaml` in your current directory for the package + - Populates as many of the fields in the `stone.yaml` file as it can automatically identify + - Checks the Sha256sum of the source code and inputs this in the recipe +2) Creates a new `monitoring.yaml` file in your current directory for the package + - Populates as many of the fields in the `monitoring.yaml` file as it can automatically identify -3. Place the URL and checksum into the `upstreams` section, then remove the temporary tarball. +Using Nano as an example, the generated `stone.yaml` file will look like this: ```yaml +# +# SPDX-FileCopyrightText: © 2025- AerynOS Developers +# +# SPDX-License-Identifier: MPL-2.0 +# +name : nano +version : 8.7 +release : 1 +homepage : https://www.nano-editor.org/dist/v8 upstreams : - - https://www.nano-editor.org/dist/v8/nano-8.6.tar.xz : f7abfbf0eed5f573ab51bd77a458f32d82f9859c55e9689f819d96fe1437a619 + - https://www.nano-editor.org/dist/v8/nano-8.7.tar.xz : afd287aa672c48b8e1a93fdb6c6588453d527510d966822b687f2835f0d986e9 +summary : UPDATE SUMMARY +description : | + UPDATE DESCRIPTION +license : + - GFDL-1.2-invariants-or-later + - GFDL-1.2-no-invariants-or-later + - GFDL-1.2-or-later + - GPL-3.0-or-later + - GFDL-1.2-no-invariants-only + - GFDL-1.2-invariants-only + - GFDL-1.2-only + - GPL-3.0-only +builddeps : + - pkgconfig(ncurses) + - pkgconfig(ncursesw) +setup : | + %configure +build : | + %make +install : | + %make_install ``` -### Step 4 · Capture a meaningful description +The second is a `monitoring.yaml` file which we will address later in this guide. + +### Step 2 - Add core metadata fields + +The `boulder recipe new` command has already made an attempt to populate the `name`, `version`, `release` and `homepage`. Please review these and correct them if necessary. -Pull a concise paragraph from upstream documentation or write one that explains what the package provides. Wrap at ~80 characters to keep reviews readable. Multi-line strings belong under the `description` block using the `|` YAML literal syntax. +In this case, the following changes need to be made: + +- Correct the `homepage` to `https://www.nano-editor.org/`. +- Update the `summary` to reflect the GNU Text Editor. +- Fill in the `description` field with a brief description of Nano. ```yaml +name : nano +version : 8.7 +release : 1 +homepage : https://www.nano-editor.org/ +upstreams : + - https://www.nano-editor.org/dist/v8/nano-8.7.tar.xz : afd287aa672c48b8e1a93fdb6c6588453d527510d966822b687f2835f0d986e9 +summary : GNU Text Editor description : | Nano is a small and simple text editor for use on the terminal. - It mirrors Pico's interface but adds undo/redo, syntax highlighting, - line numbers, soft wrapping, multiple buffers, and search/replace - with regular expressions. + It copied the interface and key bindings of the Pico editor but + added several missing features: undo/redo, syntax highlighting, + line numbers, softwrapping, multiple buffers, selecting text by + holding Shift, search-and-replace with regular expressions, and + several other conveniences. ``` -### Step 5 · Declare the license + -Find the license in upstream’s repository (often `COPYING`, `LICENSE`, or package metadata). Convert it to an SPDX identifier—Nano uses `GPL-3.0-or-later`. +### Step 3 - Declare / correct the license + +Find the license in upstream’s repository (often `COPYING`, `LICENSE`, or package metadata). Convert it to an SPDX identifier. + +Nano uses `GPL-3.0-or-later`. ```yaml license : - GPL-3.0-or-later ``` -### Step 6 · Translate prerequisites into build dependencies +### Step 4 - Translate prerequisites into build dependencies Map each upstream requirement to the package name that exists in AerynOS. Use `pkg-config()` helpers when libraries provide `.pc` files. Toolchain components like `gcc` and `make` are already available inside the build environment, so you do not have to list them. @@ -192,36 +174,34 @@ builddeps : - pkgconfig(zlib) ``` -### Step 7 · Fill in build steps +### Step 5 · Fill in build steps -Nano follows the GNU autotools flow, so use the standard macros (`%configure`, `%make`, `%make_install`). Consult the macro documentation for variations: https://aerynos.dev/packaging/macros/autotools/ . +Nano follows the GNU autotools flow, so uses the standard macros (`%configure`, `%make`, `%make_install`). These have already been populated by `boulder recipe new` so do not need to be adapted. You can consult the [macros](/packaging/macros/) documentation for variations and additional guidance. -```yaml -setup : | - %configure -build : | - %make -install : | - %make_install -``` - -### Step 8 · Review the finished recipe +### Step 6 · Review the finished recipe -Combining all of the steps gives you a complete `stone.yaml`: +Combining all the prior steps gives you a complete `stone.yaml`: ```yaml +# +# SPDX-FileCopyrightText: © 2025- AerynOS Developers +# +# SPDX-License-Identifier: MPL-2.0 +# name : nano -version : "8.6" +version : 8.7 release : 1 homepage : https://www.nano-editor.org/ upstreams : - - https://www.nano-editor.org/dist/v8/nano-8.6.tar.xz : f7abfbf0eed5f573ab51bd77a458f32d82f9859c55e9689f819d96fe1437a619 + - https://www.nano-editor.org/dist/v8/nano-8.7.tar.xz : afd287aa672c48b8e1a93fdb6c6588453d527510d966822b687f2835f0d986e9 summary : GNU Text Editor description : | Nano is a small and simple text editor for use on the terminal. - It mirrors Pico's interface but adds undo/redo, syntax highlighting, - line numbers, soft wrapping, multiple buffers, and search/replace - with regular expressions. + It copied the interface and key bindings of the Pico editor but + added several missing features: undo/redo, syntax highlighting, + line numbers, softwrapping, multiple buffers, selecting text by + holding Shift, search-and-replace with regular expressions, and + several other conveniences. license : - GPL-3.0-or-later builddeps : @@ -234,32 +214,113 @@ build : | %make install : | %make_install + ``` -Adjust any values that differ for your package (version numbers, dependencies, macros, etc.) before moving on. +## Update/correct the `monitoring.yaml` file -## Add monitoring metadata +Release monitoring keeps automated eyes on your package. -Release monitoring keeps automated eyes on your package. Update `monitoring.yaml` once you know the upstream identifiers: +As mentioned earlier in this guide, the `boulder recipe new` command has already attempted to create a `monitoring.yaml` file for you. + +In the case of Nano, it wasn't able to uniquely identify the project so the output was not as valuable and needs to be corrected. + +For reference, its output is as below: + +```yaml +releases: + id: ~ # https://release-monitoring.org/ and use the numeric id in the url of project + rss: ~ +security: + cpe: + - vendor: gnu + product: nano + - vendor: nano_arena_project + product: nano_arena + - vendor: viz + product: nano_id + - vendor: lenovo + product: thinkpad_x1_nano_gen_1_firmware + - vendor: nvidia + product: jetson_nano + - vendor: lenovo + product: thinkpad_x1_nano_gen_2_firmware + - vendor: lenovo + product: thinkpad_x1_nano_gen_2 + - vendor: lenovo + product: thinkpad_x1_nano_gen_1 + - vendor: nxp + product: mifare_ultralight_nano_firmware + - vendor: jtekt + product: nano_cpu_tuc-6941_firmware + - vendor: jtekt + product: nano_10gx_tuc-1157_firmware + - vendor: autelrobotics + product: evo_nano_drone_firmware + - vendor: jtekt + product: nano_safety_rs01ip_tuu-1087 + - vendor: jtekt + product: nano_safety_rs00ip_tuu-1086 + - vendor: netshieldcorp + product: nano_25_firmware + - vendor: ledger + product: nano_x_firmware + - vendor: ledger + product: nano_s_firmware + - vendor: jtekt + product: nano_cpu_firmware + - vendor: jtekt + product: nano_2et_firmware + - vendor: jtekt + product: nano_10gx_firmware + - vendor: nxp + product: mifare_ultralight_nano + - vendor: nxp + product: i.mx_8m_nano + - vendor: nvidia + product: jetson_nano_2gb + - vendor: jtekt + product: nano_safety_tuc-1085 + - vendor: jtekt + product: nano_cpu_tuc-6941 + - vendor: jtekt + product: nano_2et_tuu-6949 + - vendor: jtekt + product: nano_10gx_tuc-1157 + - vendor: autelrobotics + product: evo_nano_drone + - vendor: netshieldcorp + product: nano_25 + - vendor: ledger + product: nano_x + - vendor: ledger + product: nano_s + - vendor: jtekt + product: nano_cpu + - vendor: jtekt + product: nano_2et + - vendor: jtekt + product: nano_10gx + - vendor: magzter + product: nano_digest +``` + +Update `monitoring.yaml` once you know the upstream identifiers: 1. Search for the project on https://release-monitoring.org/ and copy the numeric `id`. 2. Add an RSS or Atom feed URL if upstream publishes one; otherwise leave `rss: ~`. 3. Check the National Vulnerability Database for a CPE string (https://nvd.nist.gov/products/cpe/search). If none exists, leave it as `~`. +Using this information we can correctly identify the id as 2046 and that there is no rss feed or cpe string. The `monitoring.yaml` file should look like this: + ```yaml releases: id: 2046 # Release Monitoring ID for nano rss: ~ # Replace when upstream publishes a feed security: - cpe: cpe:2.3:a:gnu:nano:*:*:*:*:*:*:*:* # Update if upstream changes identifiers + cpe: ~ # Update if upstream changes identifiers ``` -## Build and test - -From the recipe directory, run: - -```bash -just build -``` +## Build and test the package -This executes `boulder build …` with your `stone.yaml`. If the build fails, adjust the recipe, repeat the relevant step above, and rebuild until it succeeds. Finish by committing the new package on your feature branch and opening a pull request. +Once you have made the relevant changes to the package, you will need to build it locally. Refer to the [Building and Testing packages](/packaging/workflow/building-and-testing-packages/) page on guidance of how to do this. diff --git a/src/content/docs/Packaging/Workflow/index.mdx b/src/content/docs/Packaging/Workflow/index.mdx index e530e8d1..0aa93342 100644 --- a/src/content/docs/Packaging/Workflow/index.mdx +++ b/src/content/docs/Packaging/Workflow/index.mdx @@ -5,4 +5,4 @@ description: Understanding how moss and boulder make use of repositories in Aery --- import DirectoryList from '@components/DirectoryList.astro'; - \ No newline at end of file + diff --git a/src/content/docs/Packaging/Workflow/preparing-for-packaging.mdx b/src/content/docs/Packaging/Workflow/preparing-for-packaging.mdx new file mode 100644 index 00000000..5b62d5fe --- /dev/null +++ b/src/content/docs/Packaging/Workflow/preparing-for-packaging.mdx @@ -0,0 +1,40 @@ +--- +title: 'Preparing for packaging' +lastUpdated: 2026-01-25T12:00:00+00:00 +description: "Preparing for packaging on AerynOS" +--- +import { Aside } from '@astrojs/starlight/components'; + + +This page details prerequisite steps required before either creating a new package recipe or updating an existing package recipe. If you have not yet followed the [prerequisites](/packaging/workflow/prerequisites/) steps and [Basic Packaging Workflow](/packaging/workflow/basic-workflow/), follow those steps first before proceeding. + +## Update your clone of the recipes repository + +As a reminder, you want to ensure you have the volatile repository enabled and fully updated on your system. + +Whilst all the information can be found in the prior pages, to recap, the commands will be: + +```bash +sudo moss repo enable volatile +sudo moss sync -u +gotoaosrepo +git switch main +gh repo sync yourusername/yourfork -b main +git pull +``` + +## Switch to a new git branch + +When conducting any packaging work, it is a good idea to separate out your work in a different branch. This allows you to isolate changes you make from one package in a separate branch to changes you make to a different package in a second branch and so on. This additionally is helpful as it keeps your work separate to any underlaying changes made to the `main` recipes repository, more easily allowing you to rebase your work if needed. + +```bash +git checkout -b "branch-name" +``` + +Change "branch-name" to whatever description you feel comfortable with. Our general convention is to use the format `add-packagename` or `update-packagename` depending on whether you are adding a new package or updating an existing one. + +You can check what branch you are on and what branches you have in your repository with the following command: + +```bash +git branch -a +``` diff --git a/src/content/docs/Packaging/Workflow/submitting-a-pr.mdx b/src/content/docs/Packaging/Workflow/submitting-a-pr.mdx index fe681f7d..ab53939e 100644 --- a/src/content/docs/Packaging/Workflow/submitting-a-pr.mdx +++ b/src/content/docs/Packaging/Workflow/submitting-a-pr.mdx @@ -1,8 +1,8 @@ --- title: 'Submitting a PR' lastUpdated: 2026-01-11T21:22:00 +description: "How to submit a PR into the AerynOS repository" --- - import { Aside } from "@astrojs/starlight/components"; diff --git a/src/content/docs/Packaging/Workflow/updating-an-existing-recipe.mdx b/src/content/docs/Packaging/Workflow/updating-an-existing-recipe.mdx index c3c726fa..f810f228 100644 --- a/src/content/docs/Packaging/Workflow/updating-an-existing-recipe.mdx +++ b/src/content/docs/Packaging/Workflow/updating-an-existing-recipe.mdx @@ -1,66 +1,40 @@ --- title : 'Updating an existing package recipe' -date : 2025-08-01T14:33:00+01:00 +lastUpdated: 2026-01-25T12:00:00+00:00 +description: "How to update an existing package recipe" --- import { Aside } from '@astrojs/starlight/components'; -This page details the process of updating a package that is already present in the [AerynOS repository](https://github.com/AerynOS/recipes). -Before updating the package yourself, please double check that there isn't already an outstanding PR for the update you want to make. Please also check if someone has created an update request issue in the [AerynOS recipes repository](https://github.com/AerynOS/recipes). - -## Update your clone of the recipes repository -Please refer to the [Basic Packaging Workflow](/packaging/workflow/basic-workflow/) on how to create and update your local clone of the AerynOS repository on your own system before proceeding any further. - -As a reminder, you want to ensure you have the volatile repository enabled and fully updated on your system. - -For a recap, if you have followed the previous guide, the commands will be: - -``` -sudo moss repo enable volatile -sudo moss sync -u -gotoaosrepo -git switch main -gh repo sync yourusername/yourfork -b main -git pull -``` - -Change `yourusername` to your github username and `yourfork` to the name you selected for your fork of the AerynOS repository. By default the fork is called `recipes`. - -## Switch to a new git branch +This guide details the process of updating a package that is already present in the [AerynOS repository](https://github.com/AerynOS/recipes). We will use GNU Nano as the running example, but the same steps apply to any existing package. -When conducting any packaging work, it is a good idea to separate out your work in a different branch. This allows you to isolate changes you make from one package in a separate branch to changes you make to a different package in a second branch and so on. This additionally is helpful as it keeps your work separate to any underlaying changes made to the main recipes repository, more easily allowing you to rebase your work if needed. - -``` -git checkout -b update_packagename -``` +Before updating the package yourself, please double check that there isn't already an outstanding PR for the update you want to make. Please also check if someone has created an update request issue in the [AerynOS recipes repository](https://github.com/AerynOS/recipes). -Change "update_packagename" to whatever description you feel comfortable with. +## Prepare your workspace -You can check what branch you are on and what branches you have in your repository with the following command: +Prior to starting, ensure you have followed the [prerequisites](/packaging/workflow/prerequisites/) set up process, the [Basic Packaging Workflow](/packaging/workflow/basic-workflow/) and updated your system in accordance with [Preparing for Packaging](/packaging/workflow/preparing-for-packaging/) guide. -``` -git branch -a -``` +If you have not done this, follow those steps first before proceeding. ## Simple updates to a package -To update a package to a newer available version, navigate to the relevant folder within your local recipe repository on your system. If you have already navigated to the local recipe repository, then by way of example, to navigate to the nano package folder, you would use the command: +To update a package to a newer available version, navigate to the relevant folder within your local recipe repository on your system. If you have already navigated to the local recipe repository, then by way of example, to navigate to the Nano package folder, you would use the command: -``` +```bash chpkg nano ``` ### Bumping a package -If there are changes to dependencies of a package, but not to the package tiself, you need to increase the release number within the stone.yaml recipe file by one. This will allow you to rebuild the package and test it against the newer dependences to make sure everything is working. You can do this by using the following command: +If there are changes to dependencies of a package, but not to the package itself, you need to increase the release number within the `stone.yaml` recipe file by one. This will allow you to rebuild the package and test it against the newer dependences to make sure everything is working. You can do this by using the following command: -``` +```bash just bump ``` which is a shortcut for -``` +```bash boulder recipe bump ``` @@ -70,14 +44,14 @@ Please note each time you do this, you will increase the release number by one, If you need to update the package version itself, you can use the following command: -``` +```bash boulder recipe update --ver "version name" --upstream "upstream URL" stone.yaml -w ``` -In the example of nano, to update to version 8.5, you would use the following command: +In the example of nano, to update to version 8.7, you would use the following command: -``` -boulder recipe update --ver 8.5 --upstream https://www.nano-editor.org/dist/v8/nano-8.5.tar.xz stone.yaml -w +```bash +boulder recipe update --ver 8.7 --upstream https://www.nano-editor.org/dist/v8/nano-8.7.tar.xz stone.yaml -w ``` This command does the following: @@ -89,84 +63,8 @@ This command does the following: ## Wider updates to a package -If there are missing dependencies or you need to make further changes to the stone.yaml recipe file, you can either use nano to make changes to the stone.yaml from within your terminal or you can use a code editor such as zed which is pre-installed on AerynOS. Guidance on how to make changes to a stone.yaml file are covered in the [Create a new package recipe](/packaging/workflow/creating-a-new-recipe/) page. - -## Build the package - -Once you have made the relevant changes to the package, you will need to build it locally. Please ensure you have followed the steps above to enable the volatile repository. If you are only updating one package, you can either keep your local repository disabled prior to building the package, or if you prefer to keep it enabled, make sure there are no other packages indexed locally that could interfere with your new package build. - -The command to build the updated package is: - -``` -just build -``` - -If the package is successfully built, you will need to move it to your local repository. You can do this using the following command: - -``` -just mv-local -``` - -If you have not yet enabled the local repository, you do this with the following command: - -``` -sudo moss repo enable local -``` - -You will then need to sync the local repository using the command: - -``` -sudo moss sync -u -``` - -Note, if you already have an older version of the package installed, you will be asked if you want to update to the new local version you have just built. If you have not yet installed this package, you would install it as normal using the command: - -``` -sudo moss install "package name" -``` - -Once you have tested the package, you can make a submission for including the update in the repository. - - - -## Checking for updates - -To simplify update tracking for package maintainers, AerynOS provides a tool called **Ent**. Ent checks recipes against upstream sources to determine whether updates are available. - -Install Ent using `moss`: - -```bash -sudo moss install ent -``` -**How Ent works** - -Ent scans the current directory and all subdirectories beneath it. It inspects each recipe `monitoring.yaml` file and compares the referenced `stone.yaml` recipe upstreams to determine whether newer versions are available. - -Because Ent operates relative to the directory in which it is executed, you can control the scope of the update check by choosing where to run the command within the recipes repository. - -***Running update checks*** - -To check for updates across all recipes, run the following command from the root of the recipes repository: - -```bash -ent check updates -``` - -You can also run this command from more specific locations: - -* **Repository root** - Checks all recipes in the repository. - -* **Letter directory (for example, `f/`)** - Checks only recipes whose names start with that letter. - -* **Specific recipe directory (for example, `f/firefox/`)** - Checks only that single recipe. +If there are further changes required to the `stone.yaml` recipe file, you can either use a text editor (such as Nano itself) or a code editor (such as Zed which is pre-installed on AerynOS) to make changes those changes. Guidance on how to make changes to a stone.yaml file are covered in the [Creating a new package recipe](/packaging/workflow/creating-a-new-recipe/) page. -For example, running the command from `f/firefox/` will check only the Firefox recipe for available updates. +## Build and test the package - +Once you have made the relevant changes to the package, you will need to build it locally. Refer to the [Building and Testing packages](/packaging/workflow/building-and-testing-packages/) page on guidance of how to do this. From 2258b9b38b2574f6fd40241cac45b2034e16f611 Mon Sep 17 00:00:00 2001 From: NomadicCore Date: Sun, 25 Jan 2026 17:33:06 +0000 Subject: [PATCH 3/4] Packaging: Add notes and important context information --- .../Workflow/building-and-testing-packages.mdx | 2 +- .../docs/Packaging/Workflow/checking-for-updates.mdx | 2 +- .../Packaging/Workflow/creating-a-new-recipe.mdx | 12 +++++++++--- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/src/content/docs/Packaging/Workflow/building-and-testing-packages.mdx b/src/content/docs/Packaging/Workflow/building-and-testing-packages.mdx index e55bd6d3..f127a935 100644 --- a/src/content/docs/Packaging/Workflow/building-and-testing-packages.mdx +++ b/src/content/docs/Packaging/Workflow/building-and-testing-packages.mdx @@ -49,6 +49,6 @@ sudo moss install "package name" Once you have tested the package, you can make a submission for including the update in the repository. -