Contributing to Alan von Palladium

August 23, 2026 · View on GitHub

First off, thank you for considering contributing to Palladium! It's people like you who will make Palladium the language where Turing's proofs meet von Neumann's performance.

Code of Conduct

We believe in:

Respectful discourse - Attack ideas, not people
Constructive feedback - "This could be better if..." not "This sucks"
Inclusive community - All backgrounds welcome, from theorem provers to bit twiddlers

How Can I Contribute?

🐛 Reporting Bugs

Before creating bug reports, please check existing issues. When creating a bug report, include:

Clear title and description
Steps to reproduce
Expected behavior
Actual behavior
Code samples (minimal reproducible example)
Environment details (OS, Palladium version)

💡 Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. Include:

Use case - Why is this needed?
Proposed solution - How should it work?
Alternatives considered - What else did you think about?
Examples - Show how it would be used

🔧 Pull Requests

Fork the repo and create your branch from main
Write clear commit messages following conventional commits
Add tests for new functionality
Update documentation as needed
Ensure all tests pass with cargo test
Run the formatter with cargo fmt
Check lints with cargo clippy

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/palladium-a.git
cd palladium-a

# Add upstream remote
git remote add upstream https://github.com/labforadvancedstudy/palladium-a.git

# Create a feature branch
git checkout -b feature/amazing-feature

# Make your changes and test
cargo test
cargo run -- compile examples/basic/hello.pd

# Commit your changes
git commit -m "feat: add amazing feature"

# Push to your fork
git push origin feature/amazing-feature

Project Structure

palladium-a/
├── src/           # Compiler source code
│   ├── lexer/     # Tokenization
│   ├── parser/    # AST generation
│   ├── typeck/    # Type checking
│   ├── codegen/   # Code generation
│   └── driver/    # Compilation driver
├── examples/      # Example programs
├── tests/         # Integration tests
└── docs/          # Documentation

Testing

Unit tests: In relevant source files
Integration tests: In tests/ directory
Example programs: In examples/ directory

Run all tests:

cargo test

Test specific module:

cargo test parser::

Documentation

Code comments: Explain "why", not "what"
Doc comments: Use /// for public items
Examples: Include in doc comments when helpful
README updates: Keep in sync with features

`file:line` citations — when to fix one you did not break

This repository puts its evidence in path:line citations, and make check-doc-evidence pins them. A pin proves a cited range has not MOVED. It cannot prove the range SUPPORTS the claim, so wrong-but-stable citations accumulate: a sweep in 2026-08 found 98 whose own prose quotes a token that is uniquely locatable elsewhere in the same file.

You will therefore meet citations that are already wrong. The standing rule, adopted 2026-08-23 after a relocation pass "fixed" 124 of 238 citations WRONG and had to be reverted whole:

Fix a citation when your change broke it, when a reviewer names it, or when you are already editing the sentence that carries it. Leave every other pre-existing wrong citation alone, and RECORD IT AS DEBT in docs/contributing/citation-and-predicate-debt.md.

Both halves are load-bearing. Fixing beyond that line turns a bug fix into a tree-wide edit nobody can review, and each "fix" is a fresh chance to relocate a citation onto unrelated code. Staying silent about the ones you leave turns known debt into invisible debt, which is how they got there — and "silent" includes naming it only in a review thread, which is why the register is a file in the tree.

A mechanical remap is not a fix. Relocating a citation with a line map preserves what it pointed at, faithfully — including when what it pointed at was already the wrong code. A remapped citation is DEBT until somebody re-derives it BY CONTENT, and in a diff it is indistinguishable from a re-verified one. That is not hypothetical: one sentence in src/codegen/mod.rs carries two citations, one hand-re-derived and one mechanically shifted, and they look identical.

When you do relocate, the procedure is in scripts/check_doc_evidence.py's docstring, and it is not optional: correct the citation BY CONTENT first, then run --update. Running --update first launders whatever now sits at that line into the pin file, and "0 MOVED" afterwards proves only that the pins agree with the docs. Prefer an exact old→new line map (difflib over the base revision) to a text search — a search silently picks the wrong one of two identical lines, and a map is an identity. Re-derive HAND-WRITTEN citations LAST, from content anchors: a hand fix goes stale the moment a later edit in the same session shifts the file it names.

The durable fix for the class is proposed, with the measurement that kills the naive version, in docs/contributing/proposed-gate-quoted-token-citations.md.

Commit Messages

Follow conventional commits:

feat: New feature
fix: Bug fix
docs: Documentation only
test: Test additions/changes
refactor: Code refactoring
style: Formatting changes
chore: Maintenance tasks

Examples:

feat: implement for loops with range syntax
fix: correct type inference for struct returns
docs: update examples README with new structure
test: add parser tests for struct returns