Contributing to herdr-splits.nvim

Thanks for your interest in improving herdr-splits.nvim! This guide covers how to set up a local development environment and submit changes.

herdr-splits.nvim is a Neovim plugin (Lua) that also ships a Herdr-side plugin (the bash scripts under scripts/ plus the herdr-plugin.toml manifest). The two halves cooperate — please consider both when making changes to navigation or resize behaviour.

Requirements

Neovim ≥ 0.10
Herdr ≥ 0.7.0 (only needed to exercise cross-pane behaviour; you can develop the Lua side without a running Herdr session)
A Herdr-compatible terminal with Option/Alt enabled (see the README's macOS notes if you're on macOS)

Repository layout

plugin/herdr-splits.lua        Neovim entrypoint
lua/herdr-splits/              Neovim plugin source
  init.lua                     setup() + public API
  nav.lua resize.lua           navigation and resizing
  win.lua                      float / sidebar classification
  sync.lua                     Herdr-side script syncing
  config.lua herdr.lua         config + core
  health.lua                   :checkhealth herdr-splits
scripts/herdr-nav.sh           Herdr-side navigation action
scripts/herdr-resize.sh        Herdr-side resize action
scripts/minimal_init.lua       Isolated Neovim test bootstrap
tests/                         mini.test suites
Makefile                       Local and CI validation commands
herdr-plugin.toml              Herdr plugin manifest (actions + metadata)

Local development setup

Neovim side

Point your plugin manager at a local clone instead of the published repo:

-- lazy.nvim
{
  dir = '~/Projects/herdr-splits',
  cond = vim.env.HERDR_ENV == '1',
  config = function()
    require('herdr-splits').setup({})
  end,
}

Changes to files under lua/ take effect after :source or a Neovim restart (unless your plugin manager hot-reloads).

Herdr side

Link the clone so Herdr loads its scripts from your working tree:

herdr plugin link /path/to/herdr-splits

After changing scripts/*.sh or herdr-plugin.toml, run herdr server reload-config to pick them up.

Coding style

Match the surrounding Lua style — indentation, quoting, and table layout in the file you're editing are the source of truth.
Run StyLua if you use it, but note that no .stylua.toml is committed yet; when one is added it will be the canonical formatter config.
Run luacheck where practical to catch undefined globals and unused variables.
Keep the bash scripts POSIX-friendly where possible; they run on both Linux and macOS as declared in herdr-plugin.toml.

Validation

The Make targets initialize and update the pinned test dependency automatically. To prepare it separately, run make deps.

Run the automated checks with:

make test         # isolated mini.test suite in headless Neovim
make check-shell  # bash syntax checks for both shipped scripts
make check        # all of the above

Cross-pane behaviour still requires manual validation in a Herdr session:

Load the plugin in Neovim inside a Herdr session (HERDR_ENV=1).
Run :checkhealth herdr-splits and confirm it reports no failures.
Exercise navigation (<C-h/j/k/l>) and resizing (<M-h/j/k/l>) across both Neovim splits and Herdr panes, including the edge cases you changed:
- at_edge behaviour (wrap / stop / split / custom)
- count prefixes (e.g. 3<C-h>)
- floating windows and embedded-sidebar floats
- auto-unzoom when crossing into a sibling Herdr pane

Submitting changes

Fork the repo and create a branch from main.
Make focused commits with descriptive messages.
Open a pull request against main and fill in the PR template — include the manual validation steps you ran.
If your change affects user-facing behaviour or config, update README.md and, for manifest-level changes, herdr-plugin.toml.

Keep PRs scoped to one concern. Large changes are easier to review when split into smaller, independently understandable commits.

Reporting bugs and ideas

Use the GitHub issue templates (bug report / feature request). Include the output of nvim --version, your plugin manager, the Herdr version (herdr --version), and a minimal reproduction.

License

By contributing you agree that your contributions are licensed under the MIT License, the same terms as the rest of the project (see LICENSE).

4.5 KiB Raw Blame History