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.tomlinstead. -
Dependencies. Zig dependencies are declared in
build.zig.zon, and the Nix build reads them frombuild.zig.zon.nix. After changingbuild.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-serveto 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.
mainbuilds with Zig 0.17. Thezig-0.16branch 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 atdocs/agents/.