Obnam → blog → 2025 → Obnam 3: chores
  1. Goal
  2. Plan
  3. Notes
  4. Summary
  5. Comments?

Goal

The goal of today deal with leftover cruft from previous work.

  • Integrate this project to my personal CI system.
  • Add help texts to the command line.
  • Add documentation comments to all exported symbols.
  • Make it a compilation error if any help text or doc comment is missing.

The motivation for this is to get things into a good shape so that it will be easier to keep them there in the future.

Acceptance criteria for today is that the last step is done and CI runs successfully.

Plan

  • Add .radicle/ambient.yaml that runs cargo clippy, cargo doc, and cargo test, at least.
  • Run obnam help and drill down on sub-commands until everything is at least minimally documented.
  • Run cargo doc --open and browse the generated documentation and write what's missing and improve what needs it.
  • Add #![deny(missing_docs)] in the opportune place or places.
  • Verify CI runs OK.
  • Merge.

Notes

CI setup

I use Radicle CI with the Ambient adapter for my CI. This is configured with a file .radicle/ambient.yaml in the repository.

pre_plan:
  - action: cargo_fetch
plan:
  - action: cargo_clippy
  - action: cargo_build
  - action: shell
    shell: |
      export PATH=/root/.cargo/bin:/bin:/sbin
      export CARGO_TARGET_DIR=/workspace/cache
      make subplot

In addition to having my CI server run this, I've made an extension to the Radicle command line too rad to emulate what the server does locally: rad ci.

Now that I look at what's in the Obnam repository, it's all there already. Past me did good. On the other hand, I should've remembered and not added doing this to today's goal. Oh well.

CLI help text

  • I'll run cargo run -- help and make a note on everything that's missing, then add that. After that, I'll run the same for every subcommand, and sub-subcommand, and so on, until I've added everything.
  • Added texts. They're not necessarily as helpful as they could be, but I can improve them when people give me feedback.
  • Enabled the wrap_help feature for clap so that the texts are formatted for the terminal width. I don't know why this isn't the default, but oh well. Maybe it's to avoid extra dependencies? But it'd still make sense to wrap help texts at 80 columns or so, and that should not require any dependencies.
  • Pushed these changes, made sure CI runs OK, merged.

Doc comments

  • Run cargo doc --open.
  • Write write write. Also added the deny pragma for missing docs.
  • Made a few methods private that should never have been public. Having to document all exported symbols helped me notice symbols that don't need to be documented.
  • The subcommand modules are currently public so that the main program can call them. This is awkward.
  • I could deal with that by moving the main program and the subcommand module into src/bin. Done.
  • I can't seem to able to have a way for clap to fail if a command line item is missing documentation. help_expected is supposed do that, but I can't get that to work. Oh well.
  • Pushed these changes, made sure CI runs OK, merged.

Tickets

  • Closed tickets 30bdb0c, 362957d, 4cfd43b. This leaves one open issue, which I created today, about the need to have more than one chunk version.

Added a version 0 for CleartextChunk

  • For completeness.
  • Pushed these changes, made sure CI runs OK, merged.
  • Close issue e570d45.

Summary

I did a fair bit of chore type work today. This, too, is important, even though it doesn't add any new functionality.

Comments?

If you have feedback on this development session, please use the following fediverse thread: https://toot.liw.fi/@liw/114250119879708796