Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
126 lines (81 loc) · 3.84 KB

CONTRIBUTING.md

File metadata and controls

126 lines (81 loc) · 3.84 KB

Here’s a refactored version tailored to Cloth, keeping your tone (professional, clean, no fluff) and aligning with your language design, compiler, and ecosystem:

Contributing to Cloth

Thank you for your interest in contributing to Cloth. Contributions of all kinds are welcome, including language design, compiler development, tooling, documentation, and ecosystem improvements.

Getting Started

If you're new to the project, the best place to begin is by reviewing the Cloth specification and understanding the language’s core principles:

  • Deterministic memory management through hierarchical ownership
  • No garbage collector by default
  • Two-pass compilation model (symbol collection + semantic analysis/codegen)
  • Strong emphasis on performance, clarity, and maintainability

Before making changes, ensure you are familiar with the current design direction and terminology defined in the specification.

Communication and Help

If you need help or want to discuss ideas:

  • Open a discussion or issue in the repository
  • Ask questions about design decisions or implementation details
  • Propose changes before implementing large features

Cloth is still evolving, and discussion is encouraged before committing to major changes.

Areas of Contribution

You can contribute to Cloth in several areas:

Language Specification

  • Syntax and grammar improvements
  • Type system refinements
  • Ownership and memory model design
  • Error handling semantics (maybe, safe casts, fallback operators, etc.)

Compiler Development

  • Lexer, parser, and AST improvements
  • Symbol table and scope resolution
  • Type checking and diagnostics
  • Intermediate Representation (IR) design
  • LLVM backend integration and code generation

Tooling

  • Build system and package tooling
  • Formatting and linting tools
  • Language server (LSP) support
  • Debugging and profiling tools

Standard Library

  • Core utilities (cloth.io, cloth.collections, etc.)
  • Platform abstractions
  • Performance-critical primitives

Documentation

  • Specification clarity and completeness
  • Examples and usage guides
  • Tutorials and onboarding material

Making Changes

  • Keep changes focused and well-scoped
  • Follow existing naming conventions and syntax style
  • Maintain consistency with the specification
  • Update documentation when behavior changes

For larger changes:

  • Open an issue or proposal first
  • Clearly explain the problem and the proposed solution
  • Consider backward compatibility and long-term impact

Compiler and Architecture Notes

Cloth uses a structured compilation pipeline:

  1. Pass 1 — Symbol Collection

    • All modules are merged
    • Top-level declarations are registered

  2. Pass 2 — Semantic Analysis and Code Generation

    • Type checking and validation
    • Ownership and lifetime enforcement
    • IR generation
    • Backend emission (LLVM or target-specific)

Contributions should respect this model and avoid introducing implicit or order-dependent behavior.

Bug Reports

If you encounter a bug:

  • Provide a minimal reproducible example
  • Include the expected behavior vs. actual behavior
  • Attach relevant compiler output or diagnostics

For compiler errors or crashes, include:

  • Source code snippet
  • Exact error message
  • Environment details (OS, build setup, etc.)

Design Philosophy

Cloth is built with the following goals:

  • Performant — predictable, low-level control without unnecessary overhead
  • Maintainable — clear, explicit syntax designed for long-term readability
  • Productive — strong diagnostics and developer-friendly tooling
  • Memory Safe — deterministic ownership model with explicit lifetimes

All contributions should align with these principles.

If you’re unsure where to start, improving diagnostics, documentation, or small compiler components (like tokens or parsing rules) is a great entry point.