127 lines
4.5 KiB
Markdown
127 lines
4.5 KiB
Markdown
# 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](https://herdr.dev) ≥ 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:
|
|
|
|
```lua
|
|
-- 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:
|
|
|
|
```bash
|
|
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](https://github.com/JohnnyMorganz/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](https://github.com/mpeterv/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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
1. Load the plugin in Neovim inside a Herdr session (`HERDR_ENV=1`).
|
|
2. Run `:checkhealth herdr-splits` and confirm it reports no failures.
|
|
3. 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
|
|
|
|
1. Fork the repo and create a branch from `main`.
|
|
2. Make focused commits with descriptive messages.
|
|
3. Open a pull request against `main` and fill in the PR template — include the
|
|
manual validation steps you ran.
|
|
4. 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`).
|