Contributing Guidelines

Contributing Guidelines

Thank you for your interest in contributing to Tuim! We welcome bug fixes, documentation improvements, performance optimizations, and feature proposals.

---

1. Development Workflow

1. Fork and Clone:

   git clone https://github.com/<your-username>/tuim.git
   cd tuim

2. Branch from dev: The dev branch is the active integration branch. main tracks tagged stable releases.

   git checkout dev
   git checkout -b feat/your-feature-name

3. Build and Test Locally: Ensure you have Zig 0.16.0 and Neovim 0.12.0+ installed:

   zig build
   zig build test
   python3 tests/pty_integration.py

---

2. Code Style & Quality Standards

Zig Code (src/)

• Formatting: Always format Zig code with the compiler:

  zig fmt build.zig src/

• Memory Ownership: Explicit allocators only. Ensure every allocated buffer has an unambiguous owner and is freed upon destruction. Avoid global mutable state.
• Error Handling: Use Zig's error unions (!void, try, catch). Do not use @panic() in non-test production code paths.
• Bounded Operations: Background tasks must use generational cancellation and bound their execution time.

Lua Code (src/nvim/)

• Keep tuim_init.lua and terminal_init.lua clean, isolated, and fast.
• Never pollute global Neovim namespaces or write escape sequences directly to stdout (Neovim's stdout is Tuim's RPC channel).

Shell Scripts

• Run shellcheck on all modified .sh files.
• Scripts must support standard POSIX or explicit bash semantics and handle spaces in paths properly.

---

3. Pull Request Checklist

Before submitting a Pull Request, ensure:

• zig fmt --check build.zig src/main.zig src/nvim/ui_protocol.zig src/tui/renderer.zig passes without changes.
• zig build test passes with 0 errors.
• python3 tests/pty_integration.py completes cleanly.
• Relevant shell scripts pass shellcheck.
• Commit messages clearly describe the problem and solution.
• Platform claims are verified with actual observed runs (see Terminal Compatibility Matrix).

---

Next Steps

Explore the full keybindings summary in Keybindings Cheat Sheet.