Contributing to Zen C

May 8, 2026 ยท View on GitHub

First off, thank you for considering contributing to Zen C! It's people like you that make this project great.

We welcome all contributions, whether it's fixing bugs, adding documentation, proposing new features, or just reporting issues.

How to Contribute

The general workflow for contributing is:

  1. Fork the Repository: Use the standard GitHub workflow to fork the repository to your own account.
  2. Create a Feature Branch: Create a new branch for your feature or bugfix. This keeps your changes organized and separate from the main branch. 
    git checkout -b feature/NewThing
  3. Make Changes: Write your code or documentation changes.
  4. Verify: Ensure your changes work as expected and don't break existing functionality (see Running Tests).
  5. Submit a Pull Request: Push your branch to your fork and submit a Pull Request (PR) to the main Zen C repository.

Issues and Pull Requests

We use GitHub Issues and Pull Requests to track bugs and features. To help us maintain quality:

  • Use Templates: When opening an Issue or PR, please use the provided templates.
    • Bug Report: For reporting bugs.
    • Feature Request: For suggesting new features.
    • Pull Request: For submitting code changes.
  • Be Descriptive: Please provide as much detail as possible.
    • Automated Checks: We have an automated workflow that checks the description length of new Issues and PRs. If the description is too short (< 50 characters), it will be automatically closed. This is to ensure we have enough information to help you.

Development Guidelines

Code Style

  • Follow the existing C style found in the codebase. Consistency is key.
  • Use make format to auto-format all source files with the provided .clang-format.
  • Use make lint to verify formatting and check shell scripts.
  • An .editorconfig file is provided for consistent editor settings (4-space indent, UTF-8, LF endings).
  • Pre-commit hooks: Install with pip install pre-commit && pre-commit install to automatically check formatting, trailing whitespace, and shell scripts before each commit.
  • Keep code clean and readable.

Project Structure

If you are looking to extend the compiler, here is a quick map of the codebase:

  • Parser: src/parser/ - Contains the recursive descent parser implementation.
  • Codegen: src/codegen/ - Contains the transpiler logic that converts Zen C to GNU C/C11.
  • Standard Library: std/ - The standard library modules, written in Zen C itself.

Running Tests

The test suite is your best friend when developing. Please ensure all tests pass before submitting a PR.

Run All Tests

make test

Run Specific Test

./zc run tests/language/control_flow/test_match.zc

Or via the test runner:

make test only="tests/language/control_flow/test_match.zc"

Test with Different Backends

./tests/scripts/run_tests.sh --cc clang    # Clang
./tests/scripts/run_tests.sh --cc zig      # Zig cc
./tests/scripts/run_tests.sh --cc tcc      # Tiny C Compiler

Specialized Test Suites

make test-lsp      # LSP integration tests
make test-tcc      # Full suite with TCC backend
make test-misra    # MISRA C compliance checks
make test-asan     # AddressSanitizer / UBSan tests

Warnings as Errors

To build with -Werror (recommended before submitting a PR):

make clean && make WERROR=1 -j$(nproc)

Pull Request Process

  1. Ensure you have added tests for any new functionality.
  2. Ensure all existing tests pass.
  3. Update the documentation (Markdown files in docs/ or README.md) if appropriate.
  4. Describe your changes clearly in the PR description. Link to any related issues.

Thank you for your contribution!