Deviation Records #

Creating a Deviation Record #

1. Create a new file in docs/deviations/ with the next available ID (e.g., 0001-my-deviation.md)
2. Fill in all sections using the template below
3. Add an entry to the deviation index
4. Submit as part of your pull request

When to Write a Deviation Record #

Write a deviation record when this project's behavior intentionally differs from Brett Terpstra's doing. Deviations may include:

• Commands with different syntax or argument handling
• Output format changes that could break existing scripts
• Features that are not supported or deliberately omitted
• Default values or configuration that differ from the original
• Behavior changes in how entries, tags, or sections are managed

Every user-visible difference from the original CLI should have a corresponding deviation record so that users migrating from Brett's doing can understand what changed and why.

Deviation Structure #

Each deviation record describes:

• Scope: Which command, flag, or feature area is affected
• Original behavior: How Brett's doing handles it
• Our behavior: What this project does instead
• Rationale: Why we chose to deviate
• Migration: How users coming from the original can adapt

Template #

---
id: 0000
title: Deviation Title
scope: []
tags: []
created: YYYY-MM-DD
---

# DEV-0000: Title

## Summary

One sentence describing the deviation.

## Scope

Which command(s), flag(s), or feature area(s) are affected.

## Original Behavior

How Brett Terpstra's `doing` handles this. Include examples where helpful.

## Our Behavior

What this project does instead. Include examples where helpful.

## Rationale

Why we chose to deviate from the original behavior.

## Migration

How users coming from the original `doing` can adapt their workflows or scripts.

## References

- Related ADRs, issues, or external resources