Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (90 loc) · 4.04 KB

CONTRIBUTING.md

File metadata and controls

134 lines (90 loc) · 4.04 KB

Contributing to zsh-smart-insert

Thank you for your interest in contributing to zsh-smart-insert! 🎉

This project aims to improve Zsh productivity with file-aware command insertion using fzf, fd, and ripgrep, while keeping the experience ergonomic and extensible.

🚀 How to Contribute

  1. Fork this repository

  2. Clone your fork:

    git clone https://github.com/lgdevlop/zsh-smart-insert.git

  3. Create a new branch:

    git checkout -b feature/my-contribution

  4. Make your changes

  5. Submit a Pull Request to the main branch

📂 Types of Contributions

We welcome contributions of all kinds:

  • 🐛 Bug fixes
  • ⚡ Performance or compatibility improvements
  • 🧩 New search strategies or integrations
  • 📝 Improvements to documentation or examples
  • 🎮 UX enhancements and new keyboard shortcuts

🧪 Coding Standards

  • Use idiomatic Zsh syntax for all plugin logic
  • Comment code clearly in English
  • Use descriptive variable names (e.g., LBUFFER, prefix, selected_file)
  • Prefer readability and testability in logic
  • Test widget behavior inside real interactive terminals

✅ Test Checklist

Before submitting your PR:

  • The plugin loads without errors via zsh-smart-insert.plugin.zsh
  • Widgets behave correctly (Alt+f, Alt+g, Alt+s)
  • Prefix selection and path injection are functional
  • Previews (bat) and live fzf reloads work as expected
  • No new warnings or regressions in functionality

📦 Project Structure

.
├── zsh-smart-insert.plugin.zsh       # Plugin entry point
├── internal/                         # Interactive widgets (fzf, rg, etc.)
├── functions/                        # Reusable utility functions
├── project-docs/                     # Markdown docs (examples, shortcuts)
├── install.sh                        # Interactive CLI installer
├── scripts/                          # Local automation (e.g., release notes)
├── Makefile                          # CLI tasks for install/test/reload
└── assets/                           # Optional logos or visual assets

✍️ Commit Guidelines

This project uses Gitmoji Commit Workflow.

Please refer to COMMITS.md for types, emojis, and formatting rules.

Format:

✨ feat(scope): support plugin previews

🔐 Execution Permissions & Shebang Rules

To keep the repository clean and predictable, follow these rules regarding file permissions and shebang usage:

✅ Executable files (require +x and shebang)

File Shebang Description
install.sh #!/usr/bin/env zsh Interactive installer
scripts/*.js Optional (node CLI) Node-based tooling (CI scripts)

❌ Non-executables (no +x, no shebang)

File Why
zsh-smart-insert.plugin.zsh Source-only plugin entry
functions/*.zsh Utility shell functions
internal/*.zsh Widget logic (fzf_*)
project-docs/*.md Markdown documentation
.changeset/*.md Versioning metadata

🛠 Recommended command to clean up permissions

# Remove +x from non-executable files
find functions internal project-docs .changeset -type f \( -name '*.zsh' -o -name '*.md' \) -exec chmod -x {} \;
chmod -x zsh-smart-insert.plugin.zsh

# Add +x to true executable scripts
chmod +x install.sh
chmod +x scripts/*.js

🛡️ Code of Conduct

Please read our Code of Conduct. By contributing, you agree to follow it.

Thank you for helping improve zsh-smart-insert 💚