Sign git commits and tags with an OpenPGP key kept in Bitwarden.
zig-bwgpg CONTRIBUTING.md
3.3 kB · 89 lines
Markdown
at main

Contributing to bwgpg #

Reporting issues and sending changes #

Report issues and open pull requests on the Tangled mirror:

https://tangled.org/jcollie.dev/zig-bwgpg

The same history is also on Forgejo and Radicle (see Where this lives in the README), so a branch can be cloned from any of the three.

A report is most useful when it says which platform bwgpg ran on, which version (bwgpg --bwgpg-version), which Bitwarden or Vaultwarden server it talked to, and the exact command git ran. Leave out anything secret: no master passwords, API keys, session tokens, private keys or vault contents, and no logs that hold them.

Setting up #

Everything the build and the tests need comes from the Nix devshell:

$ git clone https://git.jcollie.dev/jeff/zig-bwgpg.git
$ cd zig-bwgpg
$ nix develop

That gives you Zig 0.17, gpg for the interop step, reuse, and zon2nix, and on x86-64 Linux, Wine for the Windows tests. The Development section of the README lists every build step and test, and what each test checks.

Before sending a change #

The workflow runs these on every push, and a change should pass all of them:

$ reuse lint
$ zig fmt --exclude zig-pkg --check .
$ zig build test
$ zig build interop
$ zig build -Dtarget=x86_64-windows.win10_rs4-gnu
$ zig build test -Dtarget=x86_64-windows.win10_rs4-gnu -fwine
$ nix build .#checks.x86_64-linux.home-manager

A change to the agent, the Bitwarden client, or remote signing should also pass the NixOS tests that cover it. These boot virtual machines and need KVM:

$ nix build -L .#checks.x86_64-linux.vaultwarden
$ nix build -L .#checks.x86_64-linux.ssh
$ nix build -L .#checks.x86_64-linux.tailnet

A bug fix should come with a test that fails without it.

Conventions #

  • Licensing. bwgpg is MIT licensed and follows REUSE. Every new file starts with an SPDX header like the ones already in the tree. A file that cannot hold one is covered in REUSE.toml instead.

  • Dependencies. Zig dependencies are declared in build.zig.zon, and the Nix build reads them from build.zig.zon.nix. After changing build.zig.zon, regenerate that file and commit the two together:

    $ nix develop -c zon2nix --17 --nix=build.zig.zon.nix build.zig.zon
    
  • Documentation. The API documentation is generated from doc comments and published at https://jeff.jcollie.page/zig-bwgpg/, so explain the why of a public declaration in its doc comment. Run zig build docs-serve to read the result locally. A change that users will see also updates the README, which describes bwgpg as it is now rather than how it changed.

  • Commit messages. The subject is a plain sentence saying what the change does, with no type prefix. The body explains why, and what was wrong before, if it isn't obvious from the diff.

  • Zig versions. main builds with Zig 0.17. The zig-0.16 branch carries the last release for Zig 0.16 and takes only critical fixes.

  • Releases are made by the maintainer from a tag, as the README describes.

  • Coding agents read AGENTS.md, which points them at docs/agents/.