/ NEWS.md
NEWS.md
1 # Release notes for Ambient CI 2 3 This file summarizes the user-visible changes to `ambient-ci` 4 between releases. 5 6 ## Version 0.13.1, released 2026-03-06 7 8 * A bug that caused a panic in how the sequence of run log messages is parsed 9 to create synthetic log messages has been fixed. 10 11 12 ## Version 0.13.0, released 2026-03-04 13 14 Other changes: 15 16 * The HTML run log has been improved in various ways. 17 18 - Custom action output is included. 19 - Log messages say which part of a CI run they come from. 20 - The log page is also divided into sections, based on log message 21 source. 22 - The HTML log uses synthesized log message to hide repetitive 23 steps like "prepare to create directory" followed by "successfully 24 created directory". The user now only sees "created directory" by 25 default, but can click that open to see all the details. 26 As part of this change, the library part for non-synthetic log messages 27 is gone. 28 - The raw JSON log messages are included in the HTML log, just in case 29 they are helpful some day. 30 - The VM console log is included in the HTML log to satisfy curious 31 people. 32 - Log messages and sections have HTML element IDs to allow hyper- 33 to them. 34 35 * The HTML log now passes the W3C HTML validator. 36 37 * The virtual machine console log is captured in the project state 38 directory and HTML run log. In the Ambient crate library part, the 39 `ambient_ci::qemu::QemuBuilder` now requires setting the path to the console 40 log. 41 42 * Ambient now has a lint for plan having a `deb` action and post-plan having 43 a `dput2` action or `deb2` and `dput`. The version of the actions are 44 incompatible: they put the built packages in different directories. The lint 45 catches this when a CI run starts, making the problem evident quickly. 46 47 * There is also a lint for `shell` actions referring to the old name for the 48 workspace, `/workspace`, instead of the new one, `/ci`. The old name will 49 work until further notice, but the lint is there to nudge people to switch 50 so that some day the old name can be retired safely. 51 52 * The Debian packaging now depends on `shellcheck`, for the linting Ambient 53 does for `shell` actions. 54 55 * The main error type is now called `AmbientError`, renamed from 56 `AmbientDriverError`. The old name referred to an old name for Ambient. 57 58 59 ## Version 0.12.0, released 2026-02-05 60 61 New feature: 62 63 * Ambient (`ambient run`) now produces run logs in JSON Lines format (one 64 JSON object per line of output). This can be turned into HTML pages using 65 `ambient log --format=html`. The HTML page is supposed to easier to navigate 66 than tens to thousands of kilobytes of unstructured text. It is expected that 67 the HTML logs can still be improved. They are included in a release so that 68 the Ambient developers can get feedback on how to improve them. 69 70 The parts where things fail are colored pink in the HTML log. Advice on 71 better colors and other ways to distinguish is most welcome. 72 73 To see the new logs, see <https://callisto.liw.fi/> after this release has 74 been deployed there. That should happen within an hour or two after it's 75 been uploaded to `crates.io`. 76 77 Old run logs (`run.log` in the project state directory) are no longer 78 understood by this version of Ambient. 79 80 Changed features: 81 82 * The `deb` and `deb2` actions log the package directory they create or that 83 it already exists. This helps debugging via CI run logs. 84 85 Bug fixes: 86 87 * In the `deb2` action, if the `/ci/artifacts/debian` directory doesn't exist, 88 create it. Although the `deb` and `deb2` actions share code, this doesn't 89 change anything for `deb`, as it puts the built package in `/ci/artifacts`, 90 which always exists. 91 92 ## Version 0.11.1, released 2026-01-14 93 94 Bug fix: 95 96 * Always pass UEFI OVMF firmware file to QEMU, not just when UEFI support 97 is on. The change for optional UEFI support in 0.11.0 broke some uses of 98 Ambient. This change restores functionaliy at least for my own uses. 99 100 ## Version 0.11.0, released 2025-12-20 101 102 There are more changes than usual in an Ambient release, but they should not 103 be scary. 104 105 ### Breaking changes 106 107 * The Rust Cargo related actions now use the `cargo-target` subdirectory in 108 the workspace cache directory (`/ci/cache/cargo-target`). This is invisible 109 to all common uses of Rust in Ambient projects, but allows dividing the 110 cache between different kinds of use in the future. This does mean that 111 existing caches become obsolete and should be deleted. That makes this 112 technically a breaking change. 113 114 * Ambient now checks for common problems when it loads the projects file. 115 This is know as "the linter". Currently it checks that an `rsync` target 116 has been configured if an `rsync` or `rsync2` action is used, that each file 117 downloaded by a `http_get` action has a unique filename, and that all shell 118 script snippets in `shell` actions are OK according to the `shellcheck` 119 program. 120 121 Linting can be prevented by setting `lint` to `false` in the configuration. 122 This may be necessary if, say, one of the checks is wrong. 123 124 This is a breaking change because most shell script snippets will be found 125 wanting. 126 127 * The pre- and post-plan now only allow actions that are actually meant for 128 them. Previously both allowed the same set of actions. However, actions like 129 `cargo_fetch` don't really make sense for post-plan. Now the separation is 130 more strict. 131 132 This is technically a breaking change, but hopefully doesn't actually break 133 anything for anyone. If you have a legitimate use for a pre- or post-plan 134 action that is now not allowed, let us know. 135 136 ### Problems fixed 137 138 * Some portability fixes for NixOS by invoking the Bash shell by name instead 139 of path. NixOS does not put Bash at `/bin/bash`, so using a full path 140 doesn't work reliably. Using the name should work anywhere. 141 142 * Ambient now checks, when loading the projects file, that the source location 143 for a project is a directory (following symlinks) and gives an error if it 144 is not. This means the problem is found when Ambient starts and not much 145 later when it starts running CI for a specific project. If there are many 146 projects, that might be hours later. 147 148 ### New features added 149 150 * The workspace in the VM is now `/ci`. The old name `/workspace` will work 151 indefinitely. The new name is shorter and arguably clearer. The workspace 152 is set up by `ambient-execute-plan` and so this change does not affect any 153 VM images. 154 155 * There is now a user guide for Ambient, published by CI at 156 <https://doc.liw.fi/ambient-ci/userguide.html> and included in the `deb` 157 package at `/usr/share/doc/ambient-ci/userguide.html`. The user guide 158 contains a description of each action that a project CI plan can use. The 159 guide is woefully lacking, but it's easier to add things to something that 160 exists than starting from an empty directory. 161 162 * The Ambient subplot document is formatted and published at 163 <https://doc.liw.fi/ambient-ci/ambient.html>. It may be useful for checking 164 how a specific aspect of Ambient is used. The subplot is the test suite 165 that verifies most aspects. That means it's continually run and does not 166 easily get out of date. 167 168 * New action `setenv` allows setting environment variables for later actions. 169 Using the `shell` action does not work for this, because each shell forgets 170 any changes to its environment variables when it terminates. 171 172 ~~~yaml 173 - action: setenv 174 set: 175 foo: bar 176 ~~~ 177 178 * New plan action `deb2` and post-plan actions `dput2` and `rsync2` use 179 subdirectories `debian` and `rsync` in the artifacts directory. This 180 means if a project both builds documentation and a `deb` package, they 181 don't get mixed into the same directory. Instead, documentation goes into 182 `/ci/artifacts/rsync` and the package into `/ci/artifacts/debian`. 183 184 The old actions `deb`, `dput`, and `rsync` continue to work as before and 185 use the whole artifacts directory. The new actions were added to avoid 186 changing the existing actions in an incompatible, breaking way. The old 187 actions are not deprecated. 188 189 The runnable plan versions of the old actions have changed. The plan and 190 post-plan actions result in the same runnable plan action. Changes to 191 runnable actions are not currently considered breaking changes in Ambient. 192 193 * In the VM, the `git` command is now configured by default to have "Ambient 194 CI" as the name for the user and "`ambient@example.com`" as the email 195 address. This removes the need for each project to do that in their CI plan 196 just to use `git`. 197 198 * New subcommand `ambient state` lists the projects in the Ambient state 199 directory (configuration field `state`) and the sizes of the files and 200 subdirectories they contain. The output looks like this: 201 202 ~~~json 203 { 204 "projects": { 205 "dummy": { 206 "latest_commit": "09d6a5d81a5001bf210df2bf80e871e3731f6e9f", 207 "run_log": 21370, 208 "dependencies": 472923464, 209 "cache": 2074946410, 210 "artifacts": 4096 211 }, 212 }, 213 "project_count": 6 214 } 215 ~~~ 216 217 * The `ambient qemu` subcommand has been added to execute a runnable plan in 218 a virtual machine, with or without networking. This is primarily a utility 219 command to help develop Ambient by making it easier to experiment. 220 221 * The configuration file now allows enabling UEFI use for an image. The `run` 222 and `qemu` subcommands additionally have a `--uefi` option for that. 223 224 * The `ambient qemu --persist` options allows creating a variant of an image. 225 This can be used, for example, to change a generic cloud image from Debian 226 or Arch Linux to boot fast even if the VM has no network access. Together 227 with the optional UEFI support this paves way for using generic images 228 instead of custom images for Ambient. That, in turn, should enable Ambient 229 users to run CI under other operationg systems in the VM. However, Ambient 230 needs further changes to make this convenient. 231 232 * Ambient now gives an error message if a virtual drives is too big. The 233 virtual drives are created before the virtual machine starts. Previously, 234 there was no helpful error message, only an "assert" error that only makes 235 sense to Ambient developers. 236 237 * The exported parts of the Ambient library part now all have documentation. 238 This makes the library usable from other programs, but more importantly, 239 makes it harder for Lars to forget what a type or method is for. Many typo 240 fixes and other changes were made to exported names. 241 242 Note that Ambient is probably not very useful to use as a library. If you 243 use it that way, or would like to, please be in touch and let us know so can 244 try to avoid breaking it for you. 245 246 247 ## Version 0.10.0, released 2025-11-24 248 249 * The `cargo_fetch` pre-plan action is now safer and more secure. The 250 action at its core run `cargo fetch` in the source tree. It turns out 251 `cargo` lets the source tree configure commands to run instead of 252 `rustc` etc, which means the source tree can run any program. This is 253 not acceptable. Instead, the action now pares down the source tree 254 to `Cargo.toml`, `Cargo.lock`, and `*.rs` files, which is enough to let 255 `cargo fetch` work, but removes any files that can be used to override 256 things for `cargo`. (`cargo fetch` does not build or run `build.rs`.) 257 258 * The `spawn` action has been dropped. Use the `shell` action instead. 259 260 * The run time configuration is now only logged when it's computed, 261 dropping spurious extra log spam. 262 263 * An internal change, not visible to users, is that all action implementations 264 are now in their own module, `action_impl`. This makes the codebase somewhat 265 clearer and more tidy, which will make maintenance of the actions easier in 266 the future. 267 268 269 ## Version 0.9.0, released 2025-11-13 270 271 * The `http_get` action now uses the `If-Modified-Since` HTTP request 272 header correctly. This means it won't re-download a file unless it has 273 changed on the server. 274 275 * Actions in `plan` now have the `HOME` environment variable set. It set by 276 the `ambient-execute-plan` when it executes the actions. 277 278 ## Version 0.8.0, released 2025-10-01 279 280 Breaking changes: 281 282 * It is now an error for the runnable plan given to `ambient-execute-plan`to 283 have unknown fields. This is technically a breaking change, but should not 284 actually break any valid use. The only people affected should be those who 285 write or generate their runnable plans without `ambient`. The change was made 286 to make problems in the runnable plan more explicit. 287 288 Brown paper bag bug fixes: 289 290 * `ambient` now fails a run if an action in the VM fails. This was always 291 meant to be the case, but broke at some point. There is now an explicit 292 acceptance criterion to verify this doesn't break again. 293 294 New features: 295 296 * The option `ambient plan --yaml` was added to output the plan, as loaded 297 into memory by `ambient`, in the YAML format. The default is JSON, added 298 for the sake of testing. The YAML output should help those who want to have 299 something they can rely on being at least syntactically correct. 300 301 * The option `ambient plan --runnable` was added to generate and output the 302 runnable plan for a project. This should help those who want to play with 303 `ambient-execute-plan` outside a VM. 304 305 * The action `cargo_deny` to run `cargo deny` has been added. 306 307 308 ## Version 0.7.0, released 2025-09-19 309 310 * All actions get the environment variables to use the Rust toolchain. 311 This change will eventually make it easier to have actions that set 312 environment variables for later actions, but that has not yet been 313 implemented. 314 315 * `ambient-execute-plan` now logs its own version at startup. This is 316 helpful for troubleshooting why fixes to it don't work in tests. (It's 317 usually because the tests use the wrong version of the program.) 318 319 ## Version 0.6.0, released 2025-09-19 320 321 * The `cargo_fetch` actions now runs with the `--locked` option only 322 if the `Cargo.lock` file exists. 323 324 * All actions that run `cargo` or `rustc` log their versions. 325 326 * New pre-plan action `http_get` allows downloading files into the 327 dependencies before the VM start. 328 329 * New action `cargo_doc` verifies that Rust documentation comments can 330 be formatted. 331 332 * Run log now contains stdout and stderr of any programs run by 333 actions. This especially affects `tar_extract` and `tar_create` 334 actions and will make it visible when creating a tar archive from, 335 say, the cache directory fails due to a full disk. 336 337 * License is now clarified to be GNU GPL version 3 or later. 338 Previously it was that and AGPL version 3. 339 340 ## Version 0.5.2, released 2025-09-10 341 342 * If QEMU fails, log its stderr. 343 344 ## Version 0.5.1, released 2025-08-12 345 346 * This release fixes a bug in the new `custom` action. The action is 347 now run in the source directory. 348 349 ## Version 0.5.0, released 2025-08-12 350 351 * A new, experimental action `custom` has been added. It can be used 352 in `plan`, so that it is only available in the VM. The action 353 executes a program in the `.ambient` directory at the root of the 354 source tree. This is a first step towards user-provided action 355 implementations. 356 357 ## Version 0.4.0, released 2025-07-20 358 359 Breaking changes: 360 361 * Ambient now uses `xorriso` instead of `genisoimage` to generate an 362 ISO file as a `cloud-init` local data storage. This is a breaking 363 changes, as `genisoimage` is not used even if available. Thank you 364 to Tobias Hunger. 365 366 Other changes: 367 368 * The way Ambient invokes QEMU is now more configurable, thanks to 369 Tobias Hunger. The configuration file now has a field `qemu` with 370 fields``cpu`, `memory`, `kvm_binary`, `ovmf_vars_file`, and 371 `ovmf_code_file` can be set. Of these, `cpus` and `memory` were 372 possible to set at the top level of the configuration file from 373 before. They still can be, to avoid breaking backwards 374 compatibility. The new fields take precedence. 375 376 * QEMU is now invoked with strict boot mode, system UUID, hostname, 377 and other improved settings, thanks to Tobias Hunger. 378 379 * The `target` configuration file setting is now known as 380 `rsync_target`, for clarity. Likewise the option `--target` is now 381 known as `--rsync-target`. The old names also work. 382 383 * There is now a new configuration file setting `rsync_target_base`, 384 to which the project name is joined, if `rsync_target` is not set. 385 This allows the same base target to be used for a family of projects 386 that publish their artifacts to sibling directories. 387 388 There is also a setting `rsync_target_map` to allow setting the 389 rsync target URL for each project separately. This is for 390 convenience. 391 392 * The `tmpdir` setting now defaults to `TMPDIR` in the environment, if 393 that is set. 394 395 * The `--config` option can be used many times, to allow many 396 configuration files to be loaded. This is for flexibility. 397 398 * The `--no-config` option prevents the default configuration from 399 being loaded. 400 401 * The `--version` outputs a version number, which now includes the Git 402 commit of the sources. This is to enable better remote support. 403 404 * There is some preliminary sketches of an `ambient image` group of 405 subcommands for managing a library of virtual machine images. This 406 is not really usable yet, however, because Lars Wirzenius wasn't 407 able to dedicate enough time to complete this work. It was merged, 408 and thus included in this release, so that it doesn't bit rot in an 409 abandoned branch. 410 411 * The `tar_extract` action now lists the files that are extracted. The 412 action can only be used in the plan, not in the pre- or post-plans. 413 414 * The `ambient plan` command outputs the pre-, post-, and actual plans 415 for a CI run for a project. This is meant to provide visibility as 416 to what happens. 417 418 * There are various improvements to what gets logged, but log files 419 are still mostly only useful to those familiar with the source code. 420 421 ## Version 0.3.0, released 2025-04-17 422 423 * The error message for when running `qemu-img` fails now mentions 424 `qemu-img`. Previously the error was only "File not found", which is 425 not very useful to the user. 426 427 * The error message for being unable to read a log file now mentions 428 the name of the log file. This, too, is meant to be useful to users, 429 when there's a problem. 430 431 * The result of `ambient-execute-plan` running an action in the 432 virtual machine is now shown explicitly. Previously the success of 433 executing an action was not logged, it was implicit in that the run 434 didn't end in failure. 435 436 * The `cargo_fetch`, `cargo_clippy`, and `cargo_build` actions now 437 don't use the `-vvv` option, which tells Cargo to be very, very, 438 very verbose. This is to make run logs be of a tolerable size and 439 not hide problems under a mountain of text. In the long term, 440 Ambient should produce logs where that kind of verbosity can be 441 controlled at reading time. 442 443 * The default log level for `ambient` is not `info`, previously 444 `warn`. This makes running the command a little more verbose. The 445 log level can be controlled with the `AMBIENT_LOG` environment 446 variable. 447 448 * When `ambient` makes a copy of the OVMF file (part of the UEFI 449 implementation for virtual machines) it now gives the user who runs 450 `ambeint` write permission to the copy. 451 452 * The `ambient image import` command now has a progress bar. Importing 453 computes a SHA256 checksum, which can take a while, and the progress 454 bar keeps the user amused. 455 456 * The `README.md` file now mentions how to build the code and run the 457 tests (TL;DR: `make`), and what build time dependencies are needed 458 for this. 459 460 461 ## Version 0.2.0, released 2025-03-17 462 463 There are no big changes, except the name change. The purpose of this 464 release is to update the Rust crate with the new name. 465 466 * Installation documentation are now included in the file 467 `INSTALL.md`. They aren't verified automatically, but did work when 468 tested manually at the time they were written. 469 470 * The binary has been renamed to `ambient`. The Rust crate has been 471 renamed to `ambient-ci`. The primary source code repository has been 472 moved to Radicle (repository id `rad:zwPaQSTBX8hktn22F6tHAZSFH2Fh`), 473 but the old Codeberg location will continue to work. 474 475 ## Version 0.1.0, released 2025-01-09 476 477 The first release. This was released under the name `ambient-driver`, 478 because Lars didn't think clearly.