Contributing

We welcome contributions to KiLM! This guide covers reporting issues, submitting code changes, and following our development standards.

Reporting Issues

Before creating a new issue, search the GitHub Issues page for similar reports.

Bug Reports

Include the following information:

• KiLM version: kilm --version
• KiCad version: Check Help → About KiCad
• Operating System: Windows/macOS/Linux with version
• Clear description: What happened vs. what you expected
• Reproduction steps: Minimal steps to reproduce the issue
• Error messages: Full error output (use --verbose if available)
• Configuration: Relevant parts of your config.yaml if applicable

Feature Requests

• Use case: Describe the problem you’re trying to solve
• Proposed solution: How you envision the feature working
• Alternatives: Other approaches you’ve considered
• Impact: Who would benefit from this feature

Pull Request Workflow

1. Fork and Clone

   Fork the KiLM repository and clone your fork:

   git clone https://github.com/YOUR_USERNAME/kilm.git
   cd kilm

2. Development Setup

   Follow the Development Setup guide to install dependencies.

3. Create Feature Branch

   git checkout -b feature/my-feature  # or fix/issue-123

4. Implement Changes

   Make your changes following the coding standards below.

5. Quality Checks

   Run everything CI runs; it never modifies files:

   just check

   just fix formats the code and applies safe lint fixes.

6. Commit Changes

   Use descriptive commit messages:

   git add .
   git commit -m "feat: Add library template validation"
   # or
   git commit -m "fix: Handle missing KiCad config gracefully"

7. Push and Create PR

   git push origin feature/my-feature

   Open a Pull Request with:

   • Clear description of changes
   • Link to relevant issues (“Closes #123”)
   • Screenshots/examples if applicable

Coding Standards

The full standards, project layout, and release process are in AGENTS.md. In short:

• Types: complete type hints with no Any; the ty type checker must pass.
• Gates: never weaken a ruff rule or threshold to pass a check. Every suppression names its rule and states its reason.
• Code: no emojis in code, comments, or output; pathlib.Path for paths; identical behavior on Windows, macOS, and Linux.
• Tests: a test with each feature, and a failing test first with each bug fix.
• Docs: update the command’s collocated docs.mdx when behavior changes.

Code Review Process

All Pull Requests undergo review for:

• Functionality: Does it work as intended?
• Code quality: Follows coding standards and best practices
• Type safety: Proper type annotations and no “Any” types
• Testing: Adequate test coverage
• Documentation: Clear and up-to-date

Tip

Running just check before you push saves a review round: CI runs the same command.

Getting Help

• Discussions: Use GitHub Discussions for questions
• Issues: Report bugs and request features via GitHub Issues
• Documentation: Review the Development Setup guide

Thank you for contributing to KiLM!