Development¶

Information for developers who want to modify or extend this configuration.

Prerequisites for Development¶

To work on the configuration, you need:

Neovim installed
Git for version control
Python for the installer
Lua for configuration files

Optional:

Node.js for some language servers
Cargo for Rust tools
Docker for isolated testing

Development Workflow¶

Clone the repository:

git clone https://github.com/clintonsteiner/nvim.git ~/dotfiles/nvim
cd ~/dotfiles/nvim

Create a branch for your changes:
```
git checkout -b feature/my-feature
```
Make changes to configuration files

Test your changes:

nvim  # Launch Neovim
:checkhealth  # Verify setup

Commit changes:

git add .
git commit -m "Description of changes"

Push and create a PR (if contributing):
```
git push origin feature/my-feature
```

Testing Configuration Changes¶

After modifying Lua files:

Reload configuration:

:luafile %  " Reload current file
:source %   " Source Vim config

Or restart Neovim:
```
nvim
```
Check for errors:
```
:checkhealth
:messages
```
Test affected features:
- If you modified LSP: Open a Python file, check diagnostics
- If you modified keybindings: Press <leader> to see menu
- If you modified FZF: Try <C-f> to find files

Adding New Features¶

Example: Add a new keybinding for a custom command

Create the command:

-- In lua/utils/my_commands.lua
function MyCommand()
    vim.notify("My command executed!")
end

Add keybinding:

-- In lua/plugin/which-key.lua
wk.add({
    { "<leader>mc", function() MyCommand() end, desc = "My command" }
})

Test:
```
nvim
# Press <leader>mc to test
```

Example: Add support for a new language

Create LSP config:

-- In lua/lsp/lsp.lua
lsp.gopls.setup({
    capabilities = capabilities,
    on_attach = on_attach,
})

Test:

nvim test.go
# Should have LSP features for Go

Extending Lua Configuration¶

File organization:

lua/
├── plugin/       # Plugin configurations
├── lsp/          # LSP setup
└── utils/        # Utility functions

Best practices:

Keep files focused (one concern per file)
Use clear names (my_feature.lua, not m.lua)
Document non-obvious code
Follow existing patterns
Test before committing

Example utility function:

-- In lua/utils/my_utils.lua
local M = {}

--- Description of function
-- @param arg1 string
-- @return string
function M.my_function(arg1)
    return "Result: " .. arg1
end

return M

Modifying the Installer¶

The installer is in install.py. To modify it:

Edit the file
Test it:
```
python3 install.py
```
Verify each step works correctly
Commit changes

Common modifications:

Change installation paths
Add new dependencies
Modify setup steps
Add new tools

Always test the installer thoroughly before committing!

Documentation¶

Documentation is in docs/source/. It uses Sphinx and reStructuredText.

To build documentation:

cd docs
make html

Output is in docs/_build/html/.

To add new documentation:

Create .rst file in docs/source/
Add to index.rst
Build and verify

RST syntax tips:

# Headers
============
Main Header
============

Section
-------

Subsection
^^^^^^^^^^

# Code blocks
.. code-block:: python

    print("Hello")

# Lists
- Item 1
- Item 2

# Links
`Link text <https://example.com>`_

Version Control¶

Commit message format:

Short description (under 50 chars)

Longer explanation of what and why.
Can span multiple lines.

Example:

git commit -m "Add LSP support for Go"

Branch naming:

feature/description - New features
fix/description - Bug fixes
docs/description - Documentation
refactor/description - Code cleanup

Workflow:

# 1. Create branch
git checkout -b feature/my-feature

# 2. Make changes
# ... edit files ...

# 3. Stage changes
git add .

# 4. Commit
git commit -m "Description"

# 5. Push
git push origin feature/my-feature

# 6. Create PR (optional)
# (on GitHub)

Debugging Lua Configuration¶

Print debugging:

print("Variable: " .. tostring(variable))
vim.notify("Notification message")

View in editor:

:messages  " See all notifications

Check configuration:

:set<space>  " Show current settings
:map<space>  " Show keybindings
:scriptnames " Show loaded scripts

Profile performance:

nvim --startuptime profile.log +q
# Check profile.log

Testing Guidelines¶

Before committing:

Syntax check: No Lua errors
Feature test: Your changes work
Integration test: Other features still work
Performance: No significant slowdown

Test checklist:

- [ ] No errors in :checkhealth
- [ ] :messages is clear
- [ ] Key features work (LSP, FZF, etc.)
- [ ] Startup time acceptable
- [ ] No regressions

Code Style¶

Lua style guide:

Use 4 spaces for indentation
Use clear variable names
Comment complex logic
Keep functions focused
Use local variables

Example:

-- Good
local function setup_lsp()
    local capabilities = vim.lsp.protocol.make_client_capabilities()
    -- ...
end

-- Bad
function s()
    c = vc()
    -- ...
end

Performance Considerations¶

Startup time:

# Measure
nvim --startuptime log.txt +q

# Look for slow plugins/files
sort -k2 -n log.txt | tail -20

Tips:

Lazy load plugins when possible
Avoid heavy computations in config
Use local variables (faster than globals)
Cache computed values

Optimizing plugins:

If a plugin is slow:

Check if it’s lazy-loadable
Reduce its configuration
Consider alternatives
Or disable it if rarely used

Contributing¶

If you want to contribute:

Fork the repository
Create a feature branch
Make your changes
Write tests
Update documentation
Create a pull request

Before submitting a PR:

[ ] Tests pass
[ ] Documentation updated
[ ] No breaking changes
[ ] Commit messages are clear
[ ] Code follows style guide

PR template:

## Description
What does this PR do?

## Changes
- Change 1
- Change 2

## Testing
How to test?

## Breaking Changes
Any backwards incompatible changes?

Setting Up Development Environment¶

Install development tools:

# macOS
brew install neovim python@3.11 git

# Linux
sudo apt-get install neovim python3 git

Clone repository:

git clone https://github.com/clintonsteiner/nvim.git ~/dev/nvim
cd ~/dev/nvim

Create virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt

Run tests (if tests exist):

pytest

Useful Resources¶

Troubleshooting Development¶

Configuration won’t load:

Check syntax: :checkhealth
View errors: :messages
Check file permissions: ls -la lua/

Tests failing:

Check test output for details
Run individual tests
Check dependencies

Git issues:

# View status
git status

# View changes
git diff

# Reset changes
git checkout .

# View history
git log --oneline -10

Need Help?¶

Check Troubleshooting guide
Review existing issues on GitHub
Consult Neovim documentation
Ask in Neovim community forums