zrepl is a one-stop ZFS backup & replication solution.
User Documentation can be found at zrepl.github.io.
The above does not apply if you already implemented everything. Check out the Coding Workflow section below for details.
zrepl is written in Go and uses Go modules to manage dependencies. The documentation is written in ReStructured Text using the Sphinx framework.
Dependencies:
make generate
)make generate
)Some Go code is generated, and generated code is committed to the source tree.
Therefore, building does not require having code generation tools set up.
When making changes that require code to be (re-)generated, run make generate
.
I downloads and installs pinned versions of the code generation tools into ./build/install
.
There is a CI check that ensures Git state is clean, i.e., code generation has been done by a PR and is deterministic.
Set up a Python environment that has docs/requirements.txt
installed via pip
.
Use a venv to avoid global state.
The test suite is split into pure Go tests (make test-go
) and platform tests that interact with ZFS and thus generally require root privileges (sudo make test-platform
).
Platform tests run on their own pool with the name zreplplatformtest
, which is created using the file vdev in /tmp
.
For a full code coverage profile, run make test-go COVER=1 && sudo make test-platform && make cover-merge
.
An HTML report can be generated using make cover-html
.
We use CircleCI for automated build & test pre- and post-merge.
There are two workflows:
ci
runs for every commit / branch / tag pushed to GitHub.
It is supposed to run very fast (<5min and provides quick feedback to developers).
It runs formatting checks, lints and tests on the most important OSes / architectures.
release
runs
master
Artifacts are stored in CircleCI.
Releases are issued via Git tags + GitHub Releases feature. The procedure to issue a release is as follows:
master
branch../docs/publish.sh
to re-build & push zrepl.github.io.release
pipeline (triggered via CircleCI API)Official binary releases are not re-built when Go receives an update. If the Go update is critical to zrepl (e.g. a Go security update that affects zrepl), we'd issue a new source release.
The rationale for this is that whereas distros provide a mechanism for this ($zrepl_source_release-$distro_package_revision
), GitHub Releases doesn't which means we'd need to update the existing GitHub release's assets, which nobody would notice (no RSS feed updates, etc.).
Downstream packagers can read the changelog to determine whether they want to push that minor release into their distro or simply skip it.
Makefile
in this project is not suitable for builds in distros.hier
and logging system.dist/systemd
contains a Systemd unit template../dist
, e.g. in /usr/share/zrepl/
.Makefile
's ZREPL_VERSION
variable and how it passed to Go's ldFlags
.
This is how zrepl version
knows what version number to show.
Your build system should set the ldFlags
flags appropriately and add a prefix or suffix that indicates that the given zrepl binary is a distro build, not an official one.