diff --git a/README.md b/README.md index 4fdda1b..9999446 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,68 @@ code. Package managers are a developing landscape for Lua in the context of NeoVim. Perhaps in the future, `lux` will eliminate the need to vendor this library in your application code. +#### If you are a Plugin Author + +Neovim does not have a good answer for automatic management of plugin dependencies. As such, it is recommended that library authors vendor u.nvim within their plugin. **u.nvim** is implemented in a single file, so this should be relatively painless. Furthermore, `lua/u.lua` versions are published into artifact tags `artifact-vX.Y.Z` as `init.lua` so that plugin authors can add u.nvim as a submodule to their plugin. + +
+Example git submodule setup + +```bash +# In your plugin repository +git submodule add -- https://github.com/jrop/u.nvim lua/my_plugin/u +cd lua/my_plugin/u/ +git checkout artifact-v0.2.0 # put whatever version of u.nvim you want to pin here +# ... commit the submodule within your repo + +# This would place u.nvim@v0.2.0 at: +# lua/my_plugin/u/init.lua +``` + +Then in your plugin code: + +```lua +local u = require('my_plugin.u') + +local Pos = u.Pos +local Range = u.Range +-- etc. +``` + +This approach allows plugin authors to: +- Pin to specific versions of u.nvim +- Get updates by pulling/committing new **u.nvim** versions (i.e., the usual git submodule way) +- Keep the dependency explicit and version-controlled +- Avoid namespace conflicts with user-installed plugins + +
+ +#### If you are a User + +If you want to use u.nvim in your config directly: + +
+vim.pack + +```lua +vim.pack.add { 'https://github.com/jrop/u.nvim' } +``` + +
+ +
+lazy.nvim + +```lua +{ + 'jrop/u.nvim', + lazy = true, +} +``` + +
+ + ## Signal and Rendering Usage ### Overview diff --git a/mise.toml b/mise.toml index 6cc41da..c413566 100644 --- a/mise.toml +++ b/mise.toml @@ -14,7 +14,7 @@ jq = "1.8.1" # installed. In the tests, we will override with `eval $(nvimv env VERSION)`, # but to avoid having to litter a bunch of commands with that environment # initialization, this just makes things simpler: -neovim = "0.12.0" +neovim = "0.12.1" stylua = "2.3.1" "cargo:emmylua_ls" = "0.20.0" "cargo:emmylua_check" = "0.20.0" @@ -79,12 +79,12 @@ arg "" help="The version of Neovim to test with" run = 'mise test:version:no-prep $usage_version' [tasks."test"] -run = 'mise test:version 0.12.0' +run = 'mise test:version 0.12.1' [tasks."test:all"] depends = ["test:prepare"] run = ''' -VERSIONS="0.11.5 0.12.0 nightly" +VERSIONS="0.11.5 0.12.1 nightly" for v in $VERSIONS; do mise test:version:no-prep $v done diff --git a/scripts/make-artifact-tag.sh b/scripts/make-artifact-tag.sh new file mode 100755 index 0000000..f9d7fb7 --- /dev/null +++ b/scripts/make-artifact-tag.sh @@ -0,0 +1,43 @@ +#!/usr/bin/env bash +# +# After tagging a release (say, v1.2.3), use this script to publish +# lua/u.lua in an artifact branch: artifact-v1.2.3:init.lua. To do so, +# invoke the script from the root of the repo like so: +# +# ./scripts/make-artifact-tag.sh v1.2.3 +# +# This will create a temporary orphan branch, tag it and immediately delete the +# branch. +# +set -euo pipefail + +if [[ $# -ne 1 ]]; then + echo "Usage: $0 " + exit 1 +fi + +TAG="$1" +if [[ "$(echo "$TAG" | awk '/^v[0-9]+\.[0-9]+\.[0-9]+$/ { print "YES" }')" != "YES" ]]; then + echo "Invalid tag name: expected 'vX.Y.Z'" + exit 1 +fi + +ARTIFACT_TAG="artifact-$TAG" +EXISTING_ARTIFACT_TAG=$(git tag -l "$ARTIFACT_TAG") + +if [[ "$ARTIFACT_TAG" = "$EXISTING_ARTIFACT_TAG" ]]; then + echo "Artifact tag already exists" + exit 1 +fi + +git worktree add --orphan -b "$ARTIFACT_TAG" "$ARTIFACT_TAG" +git cat-file -p "$TAG":lua/u.lua > "$ARTIFACT_TAG"/init.lua + +pushd "$ARTIFACT_TAG" +git add --all +git commit --message "$ARTIFACT_TAG" +git tag "$ARTIFACT_TAG" +popd + +git worktree remove -f "$ARTIFACT_TAG" +git branch -D "$ARTIFACT_TAG"