Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
118 lines (78 loc) · 3.9 KB

CONTRIBUTING.md

File metadata and controls

118 lines (78 loc) · 3.9 KB

🤝 Contributing to tdlist

Thank you for considering contributing to tdlist, the advanced, portable, zero-dependency todo list manager written in pure Bash. We welcome contributions that improve the usability, portability, functionality, and robustness of this project.

🧭 Guiding Principles

  • Minimalism: No required external dependencies.
  • Portability: Must run anywhere Bash + coreutils are available.
  • Clarity: Simple, readable, and maintainable Bash.
  • Fail-Safe Design: Code must handle degraded environments gracefully.
  • Extensibility: Features should be modular and easily toggleable based on system capabilities.

📌 What You Can Work On

Refer to ROADMAP.md for a detailed breakdown of planned features, optional enhancements, and future ideas.

You can contribute by:

  • Implementing core functionality (e.g., task creation, filtering, progress tracking)
  • Adding support for optional tools (e.g., fzf, dialog, notify-send)
  • Improving UX (e.g., help messages, CLI flags, output formatting)
  • Writing or updating documentation
  • Suggesting and implementing new features
  • Testing on edge-case environments (e.g., Termux, containers)
  • Fixing bugs or enhancing stability
  • Refactoring existing logic for performance or clarity

🧑‍💻 Development Standards

1. Shell Requirements

  • Use Bash, not POSIX /bin/sh.
  • Use standard coreutils (e.g., grep, awk, sed, cut).
  • Use command -v tool to detect optional tools safely.

2. Coding Style

  • All console output:
    • Should be made using the msg function.
    • Must fit within 80 columns unless its a single line.
    • Can be formatted with msg, (see msg in tdlist)
  • Unexpected errors are handled with the error function.
  • Use [[ ]] for tests instead of [ ]
  • Consistent indentation (match existing style).
  • Descriptive variable names where a variable's purpose is not obvious.
  • Functions should try to be self contained with and use local variables.
  • Use comments for logic blocks, conditionals and loops whose purpose is not obvious.
  • Document any TODOs or BUGS within nearby comments if any.

As much as it's a challenge to document all the possible rules, it is required that you match the existing style for any rules not mentioned.

3. Feature Detection Logic

If a feature relies on an external tool, use:

if [[ -x "$(command -v dialog)]]; then
    # Enable dialog ui
fi

Optional features must degrade gracefully without breaking core functionality.

4. Task File Handling

  • Format: key=value per line
  • Multiline statements i.e descriptions must be base64 encoded to fit on one line.
  • All task files stored in ~/.tdlist/tasks/ and other files with ~./tdlist

🧪 Testing

Manual testing is expected for now.

  • Try core features in different environments (minimal VM, WSL, macOS, Termux)
  • Validate features without relying on external tools
  • Confirm task parsing, listing, and editing works with edge-case inputs (empty fields, multiline descriptions, missing keys)

Automated test suite may be added in future milestones.

📤 Submitting a Pull Request

  1. Fork the repository

  2. Short branch name in context with improvements.

  3. Make changes with clear, logical commits

  4. Push and open a pull request:

    • Describe what was added/changed
    • Mention any optional tools or system dependencies added
    • Reference any related issues or roadmap items

Pull Requests must not break core functionality in a minimal Bash-only system.

🛡️ License Agreement

By contributing, you agree that your work will be released under the LICENSE.

💬 Need Help?

Open an issue to ask questions, suggest improvements, or get clarification on implementation ideas.

Thanks for helping make tdlist a reliable tool for terminal productivity across all environments.