Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
258 lines (179 loc) · 10.7 KB

CONTRIBUTING.md

File metadata and controls

258 lines (179 loc) · 10.7 KB

Contributing to CodeCompanion.nvim

Thank you for considering contributing to CodeCompanion.nvim! This document provides guidelines and information to help you get started with contributing to the project.

Before Contributing

Before contributing a PR, please open up a discussion to talk about it. While I welcome contributions that improve the plugin, I want to refrain from adding features that add little value and a lot of bloat as the plugin is already quite large (approximately 9,000 LOC).

The plugin has adopted semantic versioning. As such, any PR which breaks the existing API is unlikely to be merged.

CodeCompanion is Omakase

In Japanese cuisine, omakase means "I'll leave it up to you" - the diner allows the chef to carefully select each course. CodeCompanion follows this philosophy: carefully curated features, rather than an all-you-can-eat buffet of every possible feature. In the world of LLMs, this means that CodeCompanion will never be at the bleeding edge. However, what it sacrifices in novelty, it makes up for in stability, reliability, and a great user experience.

Breaking this down:

  • Intentional over exhaustive - Each new feature is carefully considered against the whole menu rather than just the course itself
  • Complementary - New features compliment the dish rather than acting like an unnecessary side
  • Maintainable - Every addition is code that I commit to maintaining indefinitely

AI-Assisted Contributions

While CodeCompanion itself is a tool for AI-assisted development, that does not mean I am willing to accept "vibe-coded" contributions - PRs where the contributor used an LLM to generate code but doesn't deeply understand what they're submitting.

Red flags:

  • User cannot explain implementation decisions when asked
  • Code doesn't match existing architectural patterns
  • Tests appear comprehensive but don't actually validate edge cases
  • Generic LLM patterns (overly defensive coding, verbose comments)

What I Expect:

  • Understand the codebase before contributing (use the rules, read the tests, explore the architecture)
  • Own your contribution - you should be able to explain every line you submit
  • Test thoroughly - write tests that demonstrate you understand the feature
  • Iterate based on feedback - PRs are conversations, not fire-and-forget submissions

As a rule of thumb, use an LLM to create a feature OR a test. But never both.

How to Contribute

  1. Open up a discussion to propose your idea - Save yourself time and effort by checking this is a feature that aligns with the project's goals.
  2. Fork the repository and create your branch from main.
  3. Add your feature or fix to your branch.
  4. Ensure your code follows the project's coding style and conventions.
  5. Make sure your code has adequate test coverage and is well-documented.
  6. Open a pull request (PR) with a clear title and description.

Tips for Contributing

The best way to contribute to CodeCompanion is to use CodeCompanion to help you add a feature or squash a bug. Below are some useful tips to enable you to get started as quickly as possible.

Read the Docs

They're located here and are regularly updated.

Use Rules

When working inside the CodeCompanion repository, you have access to the built-in rule files. These give an LLM knowledge of how a certain aspect of the plugin has been implemented. If you're looking to add a new feature to CodeCompanion, rules are a great way of ensuring you follow existing practices and that your LLM fully understands the architecture and design decisions that have been made.

You can load rules into the chat via the Action Palette:

Or, via the /rules slash command.

Refer to the Tests

CodeCompanion has c. 800 tests that have been carefully crafted to give great test coverage and to act as a second source of documentation. The testing section has more on how you can create your own tests.

Project Structure

CodeCompanion.nvim is organized into several key directories:

  • lua/codecompanion/:
    • adapters/: Adapters for different LLM providers (OpenAI, Anthropic, etc.)
    • interactions/:
      • chat/: Chat buffer implementation
      • inline/: Inline code editing functionality
      • cmd/: Command-line editing
    • providers/: Integration of providers (e.g. Snacks.nvim, Telescope.nvim)
    • utils/: Utility functions
  • doc/: The documentation for the CodeCompanion site and vim docs
  • queries/: Tree-sitter queries for various languages
  • tests/: Various tests for the plugin

Development Environment

Prerequisites

Using the included Dockerfile

The project includes a Dockerfile to create a container where you can run the make tools, including the tests.

Usage example:

# Build the container image
docker build -t codecompanion.nvim .

# Use it to get the deps and run the tests
docker run --rm -ti -u $(id -u):$(id -g) -v "$(pwd)":/cc -w /cc codecompanion.nvim:latest make deps test

Setting Up for Development

This section explain how to setup the environment for development using lazy.nvim package manager. However you can use the package manager of your choice.

  1. Clone your fork of the repository.
  2. Define CodeCompanion configuration pointing to your local repository:
{
  dir = "/full/path/to/local/codecompanion.nvim",
  dev = true,
  dependencies = {
    { "nvim-lua/plenary.nvim" },
    -- Include any optional dependencies needed for your development
  },
  opts = {
    opts = {
      log_level = "DEBUG", -- For development
    },
    -- The rest of your configuration
  }
}

Debugging and Logging

Logging

CodeCompanion uses a hierarchical logging system that writes to a log file. You can configure the log level in your setup:

require("codecompanion").setup({
  opts = {
    log_level = "DEBUG", -- Options: ERROR, WARN, INFO, DEBUG, TRACE
  }
})

Log files are stored in Neovim's log directory, which can be found by running :checkhealth codecompanion.

Debug Chat

When developing, you can debug the message history in the chat buffer by pressing gd to open a debug window. This shows the current messages (from yourself and the LLM) alongside any adapter settings.

Debug Requests with Proxy

If you need to debug requests and responses sent to LLM providers, you can use the proxy option to forward requests to a proxy server.

A simple proxy server can be set up using mitmproxy.

  1. Follow the mitmproxy installation guide to install mitmproxy.
  2. Start mitmproxy with the web interface and listen on port 4141: mitmweb --set listen_port=4141
  3. Configure CodeCompanion to use the proxy server:
{
  dir = "/full/path/to/local/codecompanion.nvim",
  -- The rest of your configuration ...
  opts = {
    adapters = {
      opts = {
        allow_insecure = true,
        proxy = "http://127.0.0.1:4141",
      },
    }
    -- The rest of your configuration ...
  }
}

From now on, all requests will be forwarded to the proxy server.

screenshot debug request with proxy screenshot

With mitmproxy you can much more using custom scripts/hooks like simulating slower connections, patch requests, etc. Check out the documentation for more information.

Testing

CodeCompanion uses the awesome Mini.Test for all its tests. To run the full suite of tests, call:

make test

or to run a specific test file:

FILE=tests/adapters/test_openai.lua make test_file

When adding new features, please include tests in the appropriate test file under the tests/ directory.

Running tests on Windows

Note

The below guide is for native Windows. Not POSIX emulation environments such as WSL, MSYS2, or Cygwin.

In order for tests to run on Windows, please ensure the following:

  • git is in %PATH%
  • Some make is in %PATH%
  • Some C/C++ compiler is in path for Tree-sitter to get bootstrapped
  • Define the %HOME% environment variable to %HOMEDRIVE%%HOMEPATH% or %USERPROFILE%
  • Create the directory deps in the CodeCompanion root, if it doesn't exist.

For make and a compiler, running x64 Native Tools Command Prompt from Visual Studio Community 2022, provides NMake and the Visual C++ compiler, which work fine for this purpose.

From cmd.exe:

REM setup environment
IF NOT EXIST deps MD deps
SET "HOME=%HOMEDRIVE%%HOMEPATH%"
SET "PATH=%PATH%;C:\Program Files\Git\bin"
"C:\Program Files (x86)\Microsoft Visual Studio\2022\VC\Auxiliary\Build\vcvars64.bat"

REM run all tests
nmake test

REM run a single test suite
nmake FILE=tests/interactions/chat/tools/runtime/tests_cmd.lua test_file

![NOTE] You can also use Make.ps1 Powershell script to run the same commands you would run with make (format/docs/test/test_file) or just run Make.ps1 alone to execute all at once. Make sure that all the slashes are "/" in your args in order for MiniTest to work; avoid backslashes when using test_file args.

Testing Tips

Trying to understand the CodeCompanion codebase and then having to learn how to create tests can feel onerous. So to make this process easier, it's recommended to load the test rules into your chat buffer to give your LLM knowledge of how Mini.Test works.

It can also be useful to share an example test file with an LLM too.

Code Style and Conventions

  • Use stylua for formatting Lua code
  • Configuration is in stylua.toml
  • Run make format to format the code before submitting a PR
  • Type annotations are encouraged (see lua/codecompanion/types.lua) and LuaCATS site

Building Documentation

Documentation is built using panvimdoc:

make docs