* `CGO_ENABLED=1` enables CGO, which is required by the `mattn/go-sqlite3` dependency.
* `GOARCH=arm64` is only required for Apple Silicon chips.
* `-tags "fts5"` enables the FTS option with `mattn/go-sqlite3`, which handles much of the magic behind `zk`'s `--match` filtering option.
* ``-ldflags "-X=main.Version=`git describe --tags --match v[0-9]* 2> /dev/null` -X=main.Build=`git rev-parse --short HEAD`"`` will automatically set `zk`'s build and version numbers using the latest Git tag and commit SHA.
### Automated tests
The project is vetted with two different kind of automated tests: unit tests and end-to-end tests.
#### Unit tests
Unit tests are using the standard [Go testing library](https://pkg.go.dev/testing). To execute them, use the command `make test`.
They are ideal for testing parsing output or individual API edge cases and minutiae.
#### End-to-end tests
Most of `zk`'s functionality is tested with functional tests ran with [`tesh`](https://github.com/mickael-menu/tesh), which you can execute with `make tesh` (or `make teshb`, to debug whitespaces changes).
When addressing a GitHub issue, it's a good idea to begin by creating a `tesh` file in `tests/issue-XXX.tesh`. If a starting notebook state is required, it can be added under `tests/fixtures`.
If you modify the output of `zk`, you may disrupt some `tesh` files. You can use `make tesh-update` to automatically update them with the correct output.
### CI workflows
Several GitHub action workflows are executed when pull requests are merged or releases are created.
* `.github/workflows/build.yml` checks that the project can be built and the tests still pass.
* `.github/workflows/codeql.yml` runs static analysis to vet code quality.
* `.github/workflows/release.yml` submits a new version to Homebrew when a Git version tag is created.
* `.github/workflows/triage.yml` automatically tags old issues and PRs as staled.
## Releasing a new version
When `zk` is ready to be released, you can update the `CHANGELOG.md` ([for example](https://github.com/zk-org/zk/commit/ea4457ad671aa85a6b15747460c6f2c9ad61bf73)) and create a new Git version tag (for example `v0.13.0`). Make sure you follow the [Semantic Versioning](https://semver.org) scheme.
Then, create [a new GitHub release](https://github.com/zk-org/zk/releases) with a copy of the latest `CHANGELOG.md` entries and the binaries for all supported platforms.
Binaries can be created automatically using `make dist-linux` and `make dist-macos`.
Unfortunately, `make dist-macos` must be run manually on both an Apple Silicon and Intel chips. The Linux builds are created using Docker and [these custom images](https://github.com/zk-org/zk-xcompile).
This process is convoluted because `zk` requires CGO with `mattn/go-sqlite3`, which prevents using Go's native cross-compilation. Transitioning to a CGO-free SQLite driver such as [cznic/sqlite](https://gitlab.com/cznic/sqlite) could simplify the distribution process significantly.
<p>Looking for a quick usage example? <ahref="docs/getting-started.md">Let's get started</a>.</p>
</div>
## News: We Are In Maintenance Mode
> [!IMPORTANT]
> As of January 2nd, the original brain behind zk, [Mickaël
> Menu](https://github.com/mickael-menu), made the difficult decision to retire
> from zk and the suite of programs supporting it. He put out a [call for
> maintainers](https://github.com/zk-org/zk/discussions/371), which has
> garnerned enough response to enable the project to continue! So zk is
> definitely still here for you.
>
> During this transition phase, we are placing the project into a maintenance
> mode, which means we are going to address existing issues and any teething
> problems with transferring the code bases to the new
> [zk-org](https://github.com/zk-org) organisation, which is where you can now
> find all the related projects. It also gives us new maintainers the space to
> get up to speed with the code base, which will help us address new issues and
> feature requests when they come.
>
> So for now, feel free to lodge new issues, but please withold on feature
> requests until we are out of maintenance mode. This will help keep our issues
> boards concise and pr's easier to manage.
>
> The [call to maintainers](https://github.com/zk-org/zk/discussions/371) is
> still open. Please comment there if you feel commited enough to come onboard!
> PR's, ideas, discussions and conversations are still and always will be
> warmly welcomed, with or without 'maintainer' status ❤️
## Description
`zk` is a command-line tool helping you to maintain a plain text [Zettelkasten](https://zettelkasten.de/introduction/) or [personal wiki](https://en.wikipedia.org/wiki/Personal_wiki).
@ -62,7 +90,7 @@ nix-env -iA zk
### Arch Linux
You can install [the zk package](https://archlinux.org/packages/community/x86_64/zk/) from the official repos.
You can install [the zk package](https://archlinux.org/packages/extra/x86_64/zk/) from the official repos.
tjex
4 months ago