Tools Workflow

Purpose: Standardize the process for contributing and documenting tools in the /tools directory.

Audience: Developers and contributors who create or maintain project tools and scripts.

Status: Implemented

Rationale

Consistent tool organization and self-documentation ensures maintainable, discoverable and usable project utilities. This workflow enforces standards that make tools immediately useful to other team members without external documentation.

Quick Reference

  • Tool Location: /tools directory with functional subdirectories
  • Required: --help flag implementation for all tools
  • Documentation: Self-documenting via --help, categorized in README.md files
  • Guidelines: Follow tools guidelines

Workflow Steps

1. Tool Planning

Who: Contributor creating the tool

When: Before implementing a new tool

Actions:

  • Identify the appropriate functional subdirectory in /tools
  • If unclear, ask for guidance in the related issue
  • Review existing tools for similar functionality

Result: Clear placement strategy for the new tool

2. Tool Implementation

Who: Contributor

When: During tool development

Actions:

  • Implement the tool following project coding standards
  • Required: Add --help flag with comprehensive usage information
  • Follow naming conventions from tools guidelines
  • Ensure tool is executable and properly permissioned

Result: Functional tool with self-documentation

3. Documentation Update

Who: Contributor

When: After tool implementation

Actions:

  • Update the subdirectory's README.md file
  • Categorize the tool type and purpose
  • Ensure README.md explains what types of tools belong in the directory

Result: Tool is properly documented and categorized

4. Testing and Validation

Who: Contributor

When: Before submitting for review

Actions:

  • Test the --help flag displays complete usage information
  • Verify tool works as intended
  • Confirm tool follows the self-documentation philosophy

Result: Tool is ready for team use and review

Tool Documentation Philosophy

Self-Documenting Scripts

  • Every tool must implement a --help flag
  • Help output should be comprehensive and immediately useful
  • No external documentation required for basic tool usage
  • Users can get immediate help with ./tool.sh --help

Directory Organization

  • README.md files categorize tool types per directory
  • Functional subdirectories group related tools
  • Clear directory structure aids tool discovery

Examples

Example 1: Adding a New Deployment Tool

1. Identify placement: /tools/deployment/ directory
2. Implement tool with --help flag showing usage, options, examples
3. Update /tools/deployment/README.md to include new tool category
4. Test ./deploy-tool.sh --help shows complete information

Example 2: Database Utility Script

1. Place in: /tools/database/ directory
2. Implement comprehensive --help with connection examples
3. Update README.md to categorize as database management tool
4. Verify self-documentation meets philosophy requirements

Troubleshooting

Common Issues

Problem: Unclear which subdirectory to use for a tool Solution: Ask in the related issue or check existing similar tools for guidance

Problem: Tool lacks comprehensive --help documentation Solution: Review existing tools' --help output for examples of complete documentation

Problem: README.md categorization is unclear Solution: Follow existing README.md patterns in other tool subdirectories

Open Points

Notes