Contributing
Thank you for your interest in contributing to md2do!
Getting Started
Prerequisites
- Node.js 24
- pnpm 9
Setup
# Fork the repository on GitHub, then clone your fork
git clone https://github.com/<your-username>/md2do.git
cd md2do
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run tests
pnpm test:runDevelopment Workflow
Project Structure
md2do/
├── packages/
│ ├── core/ # Task parsing and filtering
│ ├── config/ # Configuration management
│ ├── todoist/ # Todoist integration
│ ├── cli/ # Command-line interface
│ ├── mcp/ # MCP server for AI
│ ├── vscode/ # VS Code extension
│ └── obsidian/ # Obsidian plugin
├── docs/ # VitePress documentation
└── README.mdMaking Changes
Create a branch:
bashgit checkout -b feature/your-feature-nameMake your changes
Run validation:
bashpnpm validateThis runs build, linting, formatting, type checking, and tests.
Add a changeset if you changed a published package (
core,cli,config,todoist,mcp):bashpnpm changesetSelect the packages you touched, choose
patchfor a bug fix orminorfor a feature, and write a one-line summary. Changes that only touchvscode,obsidian, docs, or CI don't need one.Commit your changes (including the generated
.changeset/*.mdfile):bashgit add . git commit -m "feat: your feature description"
We use Conventional Commits:
feat:- New featurefix:- Bug fixdocs:- Documentation changesrefactor:- Code refactoringtest:- Test updateschore:- Build/tooling changes
Pull Requests
Push your branch to your fork:
bashgit push origin feature/your-feature-nameOpen a pull request against
mainEnsure CI passes (lint, typecheck, tests). For first-time contributors, CI starts once a maintainer approves the workflow run.
Wait for review. Maintainers handle version bumps and releases.
Development Commands
# Build all packages
pnpm build
# Watch mode for development
pnpm dev
# Run tests once
pnpm test:run
# Run tests in watch mode
pnpm test
# Run date-sensitive suites in several timezones
pnpm test:tz
# Lint code
pnpm lint
# Fix linting issues
pnpm lint:fix
# Type check
pnpm typecheck
# Format code
pnpm format
# Check formatting
pnpm format:check
# Run all validations
pnpm validatePackage-Specific Development
# Work on core package
pnpm --filter @md2do/core dev
pnpm --filter @md2do/core test
# Work on CLI
pnpm --filter @md2do/cli dev
pnpm link:cli # Link CLI globally
# Work on MCP server
pnpm --filter @md2do/mcp devDocumentation
Edit docs in docs/ directory:
# Start docs dev server
pnpm docs:dev
# Build docs
pnpm docs:build
# Preview built docs
pnpm docs:previewTesting
We use Vitest for testing:
- Write tests in
*.test.tsfiles - Aim for high coverage on new features
- Run tests before committing
Dates and timezones
Due and completed dates are calendar dates in the user's local timezone. When you test anything that depends on "today" or compares dates:
- Build dates through the parser or with local constructors (
new Date(2026, 9, 9)), not UTC strings (new Date('2026-10-09T00:00:00Z')). - Use the shared edge cases in
packages/core/tests/helpers/time-cases.ts(midnight, DST changes, year and leap-day boundaries). - Run
pnpm test:tz, which repeats the suites in six timezones. CI runs it too. - For CLI end-to-end tests,
runCli()inpackages/cli/tests/helpers/run-cli.tstakes atzand a frozennow.
Code Style
- TypeScript strict mode
- ESLint for linting
- Prettier for formatting
- Pre-commit hooks enforce style
Reporting Bugs
Open an issue on GitHub with:
- Clear description
- Steps to reproduce
- Expected vs actual behavior
- Environment (OS, Node version, md2do version)
Suggesting Features
Open a GitHub Discussion or Issue with:
- Use case description
- Proposed solution
- Alternative approaches considered
Getting Help
- GitHub Discussions - Ask questions
- GitHub Issues - Report bugs
- Documentation - Read the docs
License
By contributing, you agree your contributions will be licensed under the MIT License.
Thank You!
Your contributions make md2do better for everyone. We appreciate your time and effort!