Contributing

Thank you for your interest in contributing to TDL!

Ways to Contribute

Report Bugs

Found a bug? Open an issue with:

1. TDL code that reproduces the issue

2. Expected behavior - what should happen

3. Actual behavior - what actually happens

4. Environment - VS Code version, OS, etc.

Request Features

Have an idea? Open an issue with:

1. Use case - what problem does this solve?

2. Proposed syntax - how would it look?

3. Examples - show it in context

4. Alternatives - other ways to achieve this?

Improve Documentation

Documentation improvements are always welcome:

• Fix typos and grammar

• Add examples

• Clarify confusing sections

• Translate to other languages

Submit Code

Ready to code? Here's how:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Write/update tests

5. Submit a pull request

---

Development Setup

Prerequisites

• Node.js 18+

• npm 9+

Clone and Install

git clone https://github.com/yourusername/architoon.git
cd architoon
npm install

Build

# Build all packages
npm run build

# Build specific package
npm run build -w @tdl/core

Test

# Run all tests
npm test

# Run specific package tests
npm test -w @tdl/core

Project Structure

architoon/
├── packages/
│   ├── tdl/           # @tdl/core - parser, layout, renderers
│   ├── tdl-mcp/       # MCP server
│   └── architoon/     # VS Code extension
├── web/               # Web editor (Next.js)
└── docs/              # Documentation

---

Code Guidelines

TypeScript

• Use TypeScript for all code

• Enable strict mode

• Add types for all public APIs

Formatting

• Use Prettier for formatting

• 2 space indentation

• Single quotes

• No semicolons

Naming

• camelCase for variables and functions

• PascalCase for types and classes

• UPPER_SNAKE_CASE for constants

Testing

• Write tests for all new features

• Maintain test coverage above 80%

• Use descriptive test names

describe('Parser', () => {
  it('should parse node with shape property', () => {
    const result = parse('@arch\n[nodes]\n  db:Database|cyl');
    expect(result.model.nodes[0].shape).toBe('cyl');
  });
});

---

Pull Request Process

Before Submitting

1. Run tests - npm test

2. Run linter - npm run lint

3. Build - npm run build

4. Update docs if needed

PR Title Format

type(scope): description

Examples:
feat(parser): add support for state diagrams
fix(renderer): correct edge label positioning
docs(spec): clarify group syntax

Types: feat, fix, docs, style, refactor, test, chore

PR Description

Include:

• What changes were made

• Why (link to issue if applicable)

• How to test

• Screenshots for UI changes

Review Process

1. Automated checks must pass

2. At least one maintainer review

3. Address feedback

4. Squash and merge

---

Documentation Guidelines

Writing Style

• Use simple, clear language

• Write for developers of all levels

• Include code examples

• Add "TODO" comments for missing images

Markdown

• Use ATX headers (#, ##, ###)

• Code blocks with language tags

• Tables for structured data

• Links to related pages

Examples

Every feature should have:

1. Minimal example showing syntax

2. Practical example showing real usage

3. Complete example in context

---

Extension Development

Want to create a TDL extension?

Extension Structure

ext:myext
├── README.md          # Documentation
├── spec.md            # Formal specification
└── examples/          # Example usage

Guidelines

1. Graceful degradation - unknown extensions shouldn't break parsing

2. Minimal syntax - keep it simple

3. Documentation - spec and examples required

4. Versioning - use semver

See the Extension Authoring Guide for details.

---

Community

Code of Conduct

Be respectful and inclusive. We follow the Contributor Covenant.

Getting Help

• GitHub Issues - bugs and features

• GitHub Discussions - questions and ideas

• Discord - real-time chat (coming soon)

Recognition

Contributors are recognized in:

• Release notes

• Contributors list

• Special thanks in documentation

---

License

By contributing, you agree that your contributions will be licensed under the project's MIT License.

---

Questions?

Open a GitHub Discussion or reach out to the maintainers.

Thank you for contributing to TDL!