Contributing to ZSH Configuration

Thank you for your interest in contributing! This guide will help you get started.

📋 Table of Contents

Quick Start
Project Structure
Development Workflow
Documentation
Testing
Code Style
Submitting Changes

Quick Start

Prerequisites

ZSH (already installed if you're using this project)
Node.js 18+ (for CLI tools)
Git (for version control)
Text editor (VS Code recommended for TypeScript support)

Setup

Clone or navigate to project:
```
cd ~/projects/dev-tools/flow-cli
```
Install dependencies:
```
npm install
```
Run tests:
```
npm test
```

Build documentation site (optional):

mkdocs serve
# Visit http://127.0.0.1:8000

Project Structure

flow-cli/
├── cli/                      # Node.js CLI integration
│   ├── adapters/             # Adapters for ZSH functions
│   ├── lib/                  # Shared library code
│   └── README.md             # CLI documentation
│
├── docs/                     # All documentation
│   ├── architecture/         # Architecture docs
│   ├── user/                 # User guides
│   ├── api/                  # API documentation
│   ├── planning/             # Planning documents
│   ├── implementation/       # Implementation tracking
│   ├── reference/            # Reference materials
│   └── archive/              # Historical documents
│
├── config/                   # Configuration files
├── scripts/                  # Utility scripts
├── test/                     # CLI tests
│
└── mkdocs.yml               # Documentation site config
```bash

**Important:** The actual ZSH configuration files live in `~/.config/zsh/` (not in this repo).

---

## Development Workflow

### Making Changes

1. **Create a feature branch:**

   ```bash
   git checkout -b feature/your-feature-name

Make your changes:
- ZSH functions: Edit files in ~/.config/zsh/functions/
- CLI adapters: Edit files in cli/adapters/
- Documentation: Edit files in docs/

Test your changes:

# CLI tests
npm test

# ZSH function tests
~/.config/zsh/tests/test-adhd-helpers.zsh

Update documentation:
- If adding features, update relevant docs in docs/
- If changing APIs, update docs/api/
- Keep CLAUDE.md in sync with major changes

Commit your changes:

git add .
git commit -m "feat: add new feature"

Commit Message Format

We use conventional commits:

<type>(<scope>): <description>

[optional body]

[optional footer]
```diff

**Types:**

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks

**Examples:**

```text
feat(cli): add project detector adapter
fix(validation): handle empty paths correctly
docs(architecture): add quick wins guide
```yaml

---

## Documentation

### Adding New Documentation

1. **Choose the right location:**

   | Content Type            | Directory                                              |
   | ----------------------- | ------------------------------------------------------ |
   | User guides             | `docs/user/`                                           |
   | Architecture            | `docs/architecture/`                                   |
   | API docs                | `docs/api/`                                            |
   | Planning                | `docs/planning/current/` or `docs/planning/proposals/` |
   | Implementation tracking | `docs/implementation/`                                 |
   | Completed work          | `docs/archive/`                                        |

2. **Follow naming conventions:**
   - Use CAPS for visibility: `PROPOSAL-feature-name.md`
   - Use descriptive names: `ALIAS-REFERENCE-CARD.md`
   - Add dates for planning: `SPRINT-REVIEW-2025-12-21.md`

3. **Use consistent format:**

   ```markdown
   # Title

   **TL;DR:** Brief summary in 3-5 bullet points

   **Last Updated:** YYYY-MM-DD

   ---

   ## Section 1

   Content...

   ---

   **Last Updated:** YYYY-MM-DD
   **See Also:** [Related Doc](link.md)

Add to mkdocs.yml navigation:

nav:
  - Section Name:
      - Page Title: path/to/file.md

Update doc-index.md if adding major documents

Documentation Guidelines

ADHD-Friendly Writing:

✅ Use visual hierarchy (headers, bullets, tables)
✅ Keep sections short (< 200 words)
✅ Add TL;DR at top of major sections
✅ Use examples liberally
✅ Provide quick wins vs long-term items

Technical Writing:

✅ Code examples should be copy-paste ready
✅ Include file paths and line numbers
✅ Link to related documents
✅ Keep language clear and direct

Testing

Running Tests

# CLI tests (Node.js)
npm test

# Specific test file
npm test -- test/test-project-detector.js

# ZSH function tests
~/.config/zsh/tests/test-adhd-helpers.zsh
```javascript

### Writing Tests

**CLI Tests (Node.js):**

```javascript
// test/test-your-feature.js

import { strict as assert } from 'assert';
import { yourFunction } from '../lib/your-module.js';

describe('Your Feature', () => {
  it('should do what it's supposed to do', async () => {
    // Arrange
    const input = 'test input';

    // Act
    const result = await yourFunction(input);

    // Assert
    assert.strictEqual(result, 'expected output');
  });
});
```zsh

**ZSH Function Tests:**

```zsh
# ~/.config/zsh/tests/test-your-feature.zsh

source ~/.config/zsh/functions/your-feature.zsh

test_your_function() {
  local result
  result=$(your_function "test input")

  if [[ "$result" == "expected output" ]]; then
    echo "✅ your_function: PASS"
    return 0
  else
    echo "❌ your_function: FAIL (got: $result)"
    return 1
  fi
}

# Run test
test_your_function
```diff

**Test Guidelines:**

- Write tests for all new features
- Test happy path + error cases
- Use descriptive test names: `should...`
- Follow AAA pattern: Arrange, Act, Assert

---

## Code Style

### JavaScript/Node.js

**General:**

- ES6 modules (`import`/`export`)
- Async/await over callbacks
- Descriptive variable names
- JSDoc comments for public APIs

**Example:**

```javascript
/**
 * Detect project type from directory
 *
 * @param {string} projectPath - Absolute path to project directory
 * @returns {Promise<string>} - Project type (e.g., 'r-package', 'node')
 * @throws {ValidationError} - If path is invalid
 */
export async function detectProjectType(projectPath) {
  validateAbsolutePath(projectPath)

  const result = await executeShellFunction(detectorScript, 'get_project_type', [projectPath])

  return mapProjectType(result)
}
```diff

### ZSH Functions

**General:**

- Follow conventions in [ZSH-DEVELOPMENT-GUIDELINES.md](docs/ZSH-DEVELOPMENT-GUIDELINES.md)
- Use `local` for all variables
- Add `--help` support
- Error messages to stderr

**Example:**

```zsh
# Load R package and run tests
# Usage: rload-test [options]
rload-test() {
  # Help text
  if [[ "$1" == "--help" ]]; then
    cat << 'EOF'
Usage: rload-test [options]

Load R package and run tests

Options:
  --filter PATTERN  Run tests matching pattern
  --help            Show this help
EOF
    return 0
  fi

  # Validate we're in R package
  if [[ ! -f "DESCRIPTION" ]]; then
    echo "Error: Not in R package directory" >&2
    return 1
  fi

  # Load and test
  local filter=""
  [[ "$1" == "--filter" ]] && filter="$2"

  devtools::load_all()
  devtools::test(filter = "$filter")
}
```yaml

---

## Submitting Changes

### Pull Request Process

1. **Ensure all tests pass:**

   ```bash
   npm test
   ~/.config/zsh/tests/test-adhd-helpers.zsh

Update documentation:
- Update relevant docs in docs/
- Add entry to changelog if major change
- Update .STATUS with your work

Create pull request:

git push origin feature/your-feature-name

PR description should include:
- What changed and why
- Link to related issues/proposals
- Screenshots (if UI changes)
- Testing instructions

Code Review

Reviewers will check:

✅ Tests pass
✅ Code follows style guidelines
✅ Documentation updated
✅ No breaking changes (or properly documented)
✅ ADHD-friendly (if user-facing)

Architecture Guidelines

When adding features that touch architecture, follow these patterns:

1. Error Handling

Use semantic error classes (see Architecture Quick Wins)
Throw errors at boundaries
Log errors with context

2. Validation

Validate at API entry points
Fail fast with clear messages
Use reusable validation functions

3. Layer Organization

lib/domain/      # Business logic (no external dependencies)
lib/use-cases/   # Application logic
lib/adapters/    # External integrations (file system, shell, etc)
lib/utils/       # Shared utilities

4. Testing

Unit tests for domain/use-cases (fast, no I/O)
Integration tests for adapters (with real dependencies)
Use in-memory adapters for testing

For full details, see:

Questions?

Documentation: See Complete Documentation Index
Architecture: See Architecture Hub
ZSH Functions: See Development Guidelines
Issues: Create a .md file in the root or docs/ directory

Recognition

Contributors who make significant improvements will be recognized in:

Project README
Documentation
Changelog

Thank you for contributing! 🎉

Last Updated: 2025-12-21 Maintainer: DT Questions? See docs/doc-index.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to ZSH Configuration

📋 Table of Contents

Quick Start

Prerequisites

Setup

Project Structure

Commit Message Format

Documentation Guidelines

Testing

Running Tests

Code Review

Architecture Guidelines

1. Error Handling

2. Validation

3. Layer Organization

4. Testing

Questions?

Recognition

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to ZSH Configuration

📋 Table of Contents

Quick Start

Prerequisites

Setup

Project Structure

Commit Message Format

Documentation Guidelines

Testing

Running Tests

Code Review

Architecture Guidelines

1. Error Handling

2. Validation

3. Layer Organization

4. Testing

Questions?

Recognition