swadhin / lsf public
/ lsf / CONTRIBUTING.md
swadhin biswas docs: add CONTRIBUTING, Code of Conduct, and Security policy · 10/15/2025
10295e1
61 lines · 2.3 KB
Raw Download

Contributing to ls-f

Thanks for your interest in contributing! This project aims to be a friendly, production-quality wrapper around GNU ls with icons, colors, and smart formatting.

Ways to Contribute

  • Report bugs and edge cases
  • Improve documentation or examples
  • Implement or polish GNU ls flags (see the compatibility table in README.md)
  • Add tests and tooling

Getting Started (Dev Setup)

  1. Fork and clone the repo
  2. Use a recent Bash (4+) and Python 3
  3. Run a quick local check:
    • ./lsf --version
    • ./lsf -x
    • ./test_flags.sh (basic sanity tests)

No build step is required. The main script is lsf; column.py is a helper used for grid formatting.

Branch, Commit, and PRs

  • Create a feature branch from main
  • Follow Conventional Commits for messages:
    • feat: add -x layout by lines
    • fix: handle escaped filenames in grid view
    • docs: update installation instructions
    • refactor:, test:, chore:, perf:, ci:, build: are also common
  • Keep commits focused and small when possible
  • Open a Pull Request with:
    • A clear description of the intent and behavior change
    • Notes on any user-facing changes (flags, output, defaults)
    • Screenshots or examples when helpful

Coding Guidelines

  • Bash
    • Prefer portability and clarity over cleverness
    • Keep exit codes and error messages helpful
    • Be careful with quoting and spaces in filenames
    • Avoid unnecessary subshells and external utilities on hot paths
  • Python (column.py)
    • Keep it dependency-free and fast (stdlib only)
    • Support row/column layouts via LSF_LAYOUT
    • Respect LSF_TABSIZE for alignment

Tests

  • Add or update quick checks in test_flags.sh
  • Include at least:
    • Happy path
    • One or two edge cases (hidden files, escaped names, long names)
  • If you change output formatting, include before/after samples in the PR description

Documentation

  • Update README.md tables if you add/adjust flag behavior
  • Add or edit docs in docs/ when appropriate (INSTALLATION, CONFIGURATION, TROUBLESHOOTING)

License and DCO

By contributing, you agree that your contributions will be licensed under the project’s MIT License (see LICENSE).

Code of Conduct

Please follow our Code of Conduct. We aim for a welcoming, respectful community.