diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 92ff52b..6840be6 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -6,5 +6,5 @@ body: attributes: label: If you have an idea, open a discussion options: - - label: I will [create a new discussion](https://github.com/mickael-menu/zk/discussions/new?category=ideas) instead of an issue. + - label: I will [create a new discussion](https://github.com/zk-org/zk/discussions/new?category=ideas) instead of an issue. diff --git a/.github/ISSUE_TEMPLATE/support.yml b/.github/ISSUE_TEMPLATE/support.yml index 2d98383..241ad0f 100644 --- a/.github/ISSUE_TEMPLATE/support.yml +++ b/.github/ISSUE_TEMPLATE/support.yml @@ -10,4 +10,4 @@ body: attributes: label: If you need help, open a discussion options: - - label: I will [create a new discussion](https://github.com/mickael-menu/zk/discussions/new?category=help) instead of an issue. + - label: I will [create a new discussion](https://github.com/zk-org/zk/discussions/new?category=help) instead of an issue. diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 869d3cb..0977861 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -16,7 +16,7 @@ jobs: lfs: 'true' - name: Set up Go - uses: actions/setup-go@v4 + uses: actions/setup-go@v5 with: go-version-file: 'go.mod' diff --git a/CHANGELOG.md b/CHANGELOG.md index b983e54..40d0b3f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,14 +6,14 @@ All notable changes to this project will be documented in this file. ### Fixed -* [#331](https://github.com/mickael-menu/zk/issues/331) Fixed parsing large notes (contributed by [@khimaros](https://github.com/mickael-menu/zk/pull/339)). +* [#331](https://github.com/zk-org/zk/issues/331) Fixed parsing large notes (contributed by [@khimaros](https://github.com/zk-org/zk/pull/339)). ## 0.14.0 ### Added -* New [`tool.shell`](docs/tool-shell.md) configuration key to set a custom shell (contributed by [@lsvmello](https://github.com/mickael-menu/zk/pull/302)). -* New [`notebook.dir`](docs/config-notebook.md) configuration key to set the default notebook (contributed by [@lsvmello](https://github.com/mickael-menu/zk/pull/304)). +* New [`tool.shell`](docs/tool-shell.md) configuration key to set a custom shell (contributed by [@lsvmello](https://github.com/zk-org/zk/pull/302)). +* New [`notebook.dir`](docs/config-notebook.md) configuration key to set the default notebook (contributed by [@lsvmello](https://github.com/zk-org/zk/pull/304)). ### Changed @@ -21,7 +21,7 @@ All notable changes to this project will be documented in this file. ### Fixed -* Fixed LSP positions using UTF-16 offsets (contributed by [@wrvsrx](https://github.com/mickael-menu/zk/pull/317)). +* Fixed LSP positions using UTF-16 offsets (contributed by [@wrvsrx](https://github.com/zk-org/zk/pull/317)). ## 0.13.0 @@ -31,14 +31,14 @@ All notable changes to this project will be documented in this file. * `zk.new` now returns the created note's content in its output (`content`), and has two new options: * `dryRun` will prevent `zk.new` from creating the note on the file system. * `insertContentAtLocation` can be used to insert the created note's content into an arbitrary location. - * A new `zk.link` command to insert a link to a given note (contributed by [@psanker](https://github.com/mickael-menu/zk/pull/284)). + * A new `zk.link` command to insert a link to a given note (contributed by [@psanker](https://github.com/zk-org/zk/pull/284)). ## 0.12.0 ### Added * LSP: Support for external URLs with `documentLink`. -* New `{{date}}` template helper to obtain a date object from natural language (contributed by [@zalegrala](https://github.com/mickael-menu/zk/pull/262)). +* New `{{date}}` template helper to obtain a date object from natural language (contributed by [@zalegrala](https://github.com/zk-org/zk/pull/262)). ``` Get a relative date using natural language: {{date "next week"}} @@ -46,7 +46,7 @@ All notable changes to this project will be documented in this file. Format a date returned by `get-date`: {{format-date (date "monday") "timestamp"}} ``` -* `zk list` now support multiple `--match`/`-m` flags, which allows to search for several tokens appearing in any order in the notes (contributed by [@rktjmp](https://github.com/mickael-menu/zk/pull/268)). +* `zk list` now support multiple `--match`/`-m` flags, which allows to search for several tokens appearing in any order in the notes (contributed by [@rktjmp](https://github.com/zk-org/zk/pull/268)). ### Changed @@ -54,19 +54,19 @@ All notable changes to this project will be documented in this file. ### Fixed -* [#243](https://github.com/mickael-menu/zk/issues/243) LSP: Fixed finding backlink references for notes in a folder. -* [#254](https://github.com/mickael-menu/zk/issues/254) Fixed SQL error when pairing `--link-to` and `--linked-by`. +* [#243](https://github.com/zk-org/zk/issues/243) LSP: Fixed finding backlink references for notes in a folder. +* [#254](https://github.com/zk-org/zk/issues/254) Fixed SQL error when pairing `--link-to` and `--linked-by`. ## 0.11.1 ### Changed -* `zk new` now requires the `--interactive`/`-i` flag to read the note body from a pipe or standard input. [See rational](https://github.com/mickael-menu/zk/pull/242#issuecomment-1182602001). +* `zk new` now requires the `--interactive`/`-i` flag to read the note body from a pipe or standard input. [See rational](https://github.com/zk-org/zk/pull/242#issuecomment-1182602001). ### Fixed -* [#244](https://github.com/mickael-menu/zk/issues/244) Fixed `zk new` waiting for `Ctrl-D` to proceed (contributed by [@pkazmier](https://github.com/mickael-menu/zk/pull/242)). +* [#244](https://github.com/zk-org/zk/issues/244) Fixed `zk new` waiting for `Ctrl-D` to proceed (contributed by [@pkazmier](https://github.com/zk-org/zk/pull/242)). ## 0.11.0 @@ -92,10 +92,10 @@ All notable changes to this project will be documented in this file. ### Fixed -* [#233](https://github.com/mickael-menu/zk/issues/233) Hide index progress in non-interactive shells. -* [#235](https://github.com/mickael-menu/zk/issues/235) Fix LSP link recognition with unicode (contributed by [@zkbpkp](https://github.com/mickael-menu/zk/issues/235)). -* [#236](https://github.com/mickael-menu/zk/issues/236) Fix updating links after creating a new note. -* [#239](https://github.com/mickael-menu/zk/discussions/239) Support standard input via shell redirection with `zk new`. +* [#233](https://github.com/zk-org/zk/issues/233) Hide index progress in non-interactive shells. +* [#235](https://github.com/zk-org/zk/issues/235) Fix LSP link recognition with unicode (contributed by [@zkbpkp](https://github.com/zk-org/zk/issues/235)). +* [#236](https://github.com/zk-org/zk/issues/236) Fix updating links after creating a new note. +* [#239](https://github.com/zk-org/zk/discussions/239) Support standard input via shell redirection with `zk new`. ## 0.10.1 @@ -114,15 +114,15 @@ All notable changes to this project will be documented in this file. ### Added * New `--date` flag for `zk new` to set the current date manually. -* New `--id` flag for `zk new` to skip ID generation and use a provided value (contributed by [@skbolton](https://github.com/mickael-menu/zk/pull/183)). -* [#144](https://github.com/mickael-menu/zk/issues/144) LSP auto-completion of YAML frontmatter tags. -* [zk-nvim#26](https://github.com/mickael-menu/zk-nvim/issues/26) The LSP server doesn't use `additionalTextEdits` anymore to remove the trigger characters when completing links. +* New `--id` flag for `zk new` to skip ID generation and use a provided value (contributed by [@skbolton](https://github.com/zk-org/zk/pull/183)). +* [#144](https://github.com/zk-org/zk/issues/144) LSP auto-completion of YAML frontmatter tags. +* [zk-nvim#26](https://github.com/zk-org/zk-nvim/issues/26) The LSP server doesn't use `additionalTextEdits` anymore to remove the trigger characters when completing links. * You can customize the default behavior with the [`use-additional-text-edits` configuration key](docs/config-lsp.md). -* [#163](https://github.com/mickael-menu/zk/issues/163) Use the `ZK_SHELL` environment variable to override the shell for `zk` only. -* [#173](https://github.com/mickael-menu/zk/issues/173) Support for double star globbing in `note.ignore` config option. -* [#137](https://github.com/mickael-menu/zk/issues/137) Customize the `fzf` options used by `zk`'s interactive modes with the [`fzf-options`](docs/tool-fzf.md) config option (contributed by [@Nelyah](https://github.com/mickael-menu/zk/pull/154)). +* [#163](https://github.com/zk-org/zk/issues/163) Use the `ZK_SHELL` environment variable to override the shell for `zk` only. +* [#173](https://github.com/zk-org/zk/issues/173) Support for double star globbing in `note.ignore` config option. +* [#137](https://github.com/zk-org/zk/issues/137) Customize the `fzf` options used by `zk`'s interactive modes with the [`fzf-options`](docs/tool-fzf.md) config option (contributed by [@Nelyah](https://github.com/zk-org/zk/pull/154)). -* [#168](https://github.com/mickael-menu/zk/discussions/168) Customize the `fzf` key binding to create new notes with the [`fzf-bind-new`](docs/tool-fzf.md) config option. +* [#168](https://github.com/zk-org/zk/discussions/168) Customize the `fzf` key binding to create new notes with the [`fzf-bind-new`](docs/tool-fzf.md) config option. ### Changed @@ -130,10 +130,10 @@ All notable changes to this project will be documented in this file. ### Fixed -* [#126](https://github.com/mickael-menu/zk/issues/126) Embedded image links shown as not found. -* [#152](https://github.com/mickael-menu/zk/issues/152) Incorrect timezone for natural dates. -* [#170](https://github.com/mickael-menu/zk/issues/170) Broken wiki links in subdirectories. -* [#185](https://github.com/mickael-menu/zk/issues/185) Don't parse a Markdown table header as a colon tag. +* [#126](https://github.com/zk-org/zk/issues/126) Embedded image links shown as not found. +* [#152](https://github.com/zk-org/zk/issues/152) Incorrect timezone for natural dates. +* [#170](https://github.com/zk-org/zk/issues/170) Broken wiki links in subdirectories. +* [#185](https://github.com/zk-org/zk/issues/185) Don't parse a Markdown table header as a colon tag. ## 0.9.0 @@ -147,10 +147,10 @@ All notable changes to this project will be documented in this file. ### Fixed -* [#111](https://github.com/mickael-menu/zk/issues/111) Filenames take precedence over folders when matching a sub-path with wiki links. -* [#118](https://github.com/mickael-menu/zk/issues/118) Fix infinite loop when parsing a single-character hashtag. -* [#121](https://github.com/mickael-menu/zk/issues/121) Take into account the `--no-input` flag with `zk init`. -* [#120](https://github.com/mickael-menu/zk/discussions/120) Support RFC 3339 dates with the time flags (e.g. `--created-before`). +* [#111](https://github.com/zk-org/zk/issues/111) Filenames take precedence over folders when matching a sub-path with wiki links. +* [#118](https://github.com/zk-org/zk/issues/118) Fix infinite loop when parsing a single-character hashtag. +* [#121](https://github.com/zk-org/zk/issues/121) Take into account the `--no-input` flag with `zk init`. +* [#120](https://github.com/zk-org/zk/discussions/120) Support RFC 3339 dates with the time flags (e.g. `--created-before`). ## 0.8.0 @@ -175,9 +175,9 @@ All notable changes to this project will be documented in this file. ### Fixed -* [#89](https://github.com/mickael-menu/zk/issues/89) Calling `zk index` from outside the notebook (contributed by [@adamreese](https://github.com/mickael-menu/zk/pull/90)). -* [#98](https://github.com/mickael-menu/zk/issues/98) Index wiki links using partial paths for `--linked-by` and `--link-to`. -* [#98](https://github.com/mickael-menu/zk/issues/98) Ignore spaces around the pipe in wiki links for LSP diagnostics. +* [#89](https://github.com/zk-org/zk/issues/89) Calling `zk index` from outside the notebook (contributed by [@adamreese](https://github.com/zk-org/zk/pull/90)). +* [#98](https://github.com/zk-org/zk/issues/98) Index wiki links using partial paths for `--linked-by` and `--link-to`. +* [#98](https://github.com/zk-org/zk/issues/98) Ignore spaces around the pipe in wiki links for LSP diagnostics. ## 0.7.0 @@ -199,7 +199,7 @@ All notable changes to this project will be documented in this file. [[book review information]] [[Information Graphics]] ``` -* Use the `{{abs-path}}` template variable when [formatting notes](docs/template-format.md) to print the absolute path to the note (contributed by [@pstuifzand](https://github.com/mickael-menu/zk/pull/60)). +* Use the `{{abs-path}}` template variable when [formatting notes](docs/template-format.md) to print the absolute path to the note (contributed by [@pstuifzand](https://github.com/zk-org/zk/pull/60)). * A new `{{substring s index length}}` template helper extracts a portion of a given string, e.g.: * `{{substring 'A full quote' 2 4}}` outputs `full` * `{{substring 'A full quote' -5 5}` outputs `quote` @@ -207,9 +207,9 @@ All notable changes to this project will be documented in this file. ### Fixed * UTF-8 handling in the LSP server. -* [#78](https://github.com/mickael-menu/zk/issues/78) Do not exclude notes containing broken links from the index. +* [#78](https://github.com/zk-org/zk/issues/78) Do not exclude notes containing broken links from the index. * Allow setting the `--working-dir` and `--notebook-dir` flags before the `zk` subcommand when using aliases, e.g. `zk -W ~/notes my-alias`. -* [#86](https://github.com/mickael-menu/zk/issues/86) Index encoded Markdown links. +* [#86](https://github.com/zk-org/zk/issues/86) Index encoded Markdown links. ## 0.6.0 @@ -223,7 +223,7 @@ All notable changes to this project will be documented in this file. * `{{json title}}` prints with quotes `"An interesting note"` * `{{json .}}` serializes the full template context as a JSON object. * Use `--header` and `--footer` options with `zk list` to print arbitrary text at the start or end of the list. -* Support for LSP references to browse the backlinks of the link under the caret (contributed by [@pstuifzand](https://github.com/mickael-menu/zk/pull/58)). +* Support for LSP references to browse the backlinks of the link under the caret (contributed by [@pstuifzand](https://github.com/zk-org/zk/pull/58)). * New [`note.ignore`](docs/config-note.md) configuration option to ignore files matching the given path globs when indexing notes. ```yaml [note] @@ -235,7 +235,7 @@ All notable changes to this project will be documented in this file. ### Fixed -* [#16](https://github.com/mickael-menu/zk/issues/16) Links with section anchors, e.g. `[[filename#section]]`. +* [#16](https://github.com/zk-org/zk/issues/16) Links with section anchors, e.g. `[[filename#section]]`. * Unicode support in wiki links. If you use accents or ideograms, please run `zk index --force` after upgrading to fix your index. @@ -243,7 +243,7 @@ All notable changes to this project will be documented in this file. ### Added -* [Editor integration through LSP](https://github.com/mickael-menu/zk/issues/22): +* [Editor integration through LSP](https://github.com/zk-org/zk/issues/22): * New code actions to create a note using the current selection as title. * Custom commands to [run `new` and `index` from your editor](docs/editors-integration.md#custom-commands). * Diagnostics to [report dead links or wiki link titles](docs/config-lsp.md). @@ -262,7 +262,7 @@ All notable changes to this project will be documented in this file. ### Fixed * Creating a new note from `fzf` in a directory containing spaces. -* Fix completion with Neovim's built-in LSP client (contributed by [@cormacrelf](https://github.com/mickael-menu/zk/pull/39)). +* Fix completion with Neovim's built-in LSP client (contributed by [@cormacrelf](https://github.com/zk-org/zk/pull/39)). ## 0.4.0 @@ -275,7 +275,7 @@ All notable changes to this project will be documented in this file. * Auto-complete [hashtags and colon-separated tags](docs/tags.md). * Preview the content of a note when hovering a link. * Navigate in your notes by following internal links. - * [And more to come...](https://github.com/mickael-menu/zk/issues/22) + * [And more to come...](https://github.com/zk-org/zk/issues/22) * See [the documentation](docs/editors-integration.md) for configuration samples. * Pair `--match` with `--exact-match` / `-e` to search for (case insensitive) exact occurrences in your notes. * This can be useful when looking for terms including special characters, such as `[[name]]`. @@ -320,7 +320,7 @@ All notable changes to this project will be documented in this file. ### Fixed -* [#4](https://github.com/mickael-menu/zk/issues/4) Terminal borked when piping content with Vim +* [#4](https://github.com/zk-org/zk/issues/4) Terminal borked when piping content with Vim ## 0.2.1 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..703e824 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,61 @@ +# Contributing to `zk` + +## Understanding the codebase + +### Building the project + +It is recommended to use the `Makefile` for compiling the project, as the `go` command requires a few parameters. + +```shell +make build +``` + +This will be expanded to the following command: + +```shell +CGO_ENABLED=1 GOARCH=arm64 go build -tags "fts5" -ldflags "-X=main.Version=`git describe --tags --match v[0-9]* 2> /dev/null` -X=main.Build=`git rev-parse --short HEAD`" +``` + +* `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. \ No newline at end of file diff --git a/README.md b/README.md index f0ac6c0..1a68a2b 100644 --- a/README.md +++ b/README.md @@ -43,8 +43,8 @@ * [Advanced search and filtering capabilities](docs/note-filtering.md) including [tags](docs/tags.md), links and mentions * [Integration with your favorite editors](docs/editors-integration.md): * [Any LSP-compatible editor](docs/editors-integration.md) - * [`zk-nvim`](https://github.com/mickael-menu/zk-nvim) for Neovim 0.5+ - * [`zk-vscode`](https://github.com/mickael-menu/zk-vscode) for Visual Studio Code + * [`zk-nvim`](https://github.com/zk-org/zk.nvim) for Neovim 0.5+ + * [`zk-vscode`](https://github.com/zk-org/zk-vscode) for Visual Studio Code * (*unmaintained*) [`zk.nvim`](https://github.com/megalithic/zk.nvim) for Neovim 0.5+ by [Seth Messer](https://github.com/megalithic) * [Interactive browser](docs/tool-fzf.md), powered by `fzf` * [Git-style command aliases](docs/config-alias.md) and [named filters](docs/config-filter.md) @@ -65,7 +65,7 @@ ## Install -[Check out the latest release](https://github.com/mickael-menu/zk/releases) for pre-built binaries for macOS and Linux (`zk` was not tested on Windows). +[Check out the latest release](https://github.com/zk-org/zk/releases) for pre-built binaries for macOS and Linux (`zk` was not tested on Windows). ### Homebrew @@ -101,7 +101,7 @@ sudo pacman -S zk Make sure you have a working [Go 1.18+ installation](https://golang.org/), then clone the repository: ```sh -$ git clone https://github.com/mickael-menu/zk.git +$ git clone https://github.com/zk-org/zk.git $ cd zk ``` diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 94cd706..f024e77 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -17,7 +17,7 @@
{{ site.description | default: site.github.project_tagline }}
{% endif %} diff --git a/docs/assets/media/list-format.svg b/docs/assets/media/list-format.svg index 934ebf8..fbc2f72 100644 --- a/docs/assets/media/list-format.svg +++ b/docs/assets/media/list-format.svg @@ -96,5 +96,5 @@