Contributing

Thank you for your interest in contributing to Quartz! We welcome contributions of all kinds — code, documentation, bug reports, feature suggestions, and more.

Getting Started

Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR-USERNAME/quartz.git
cd quartz
git remote add upstream https://github.com/quartz-org/quartz.git

Build the Project

bash build.sh

Run Tests

# Run all sanity checks
./sanity_check.sh

# Run feature checks
./feature_check.sh

# Run compile-run checks
./compile_run_check.sh

Ways to Contribute

🐛 Report Bugs

Found a bug? Open an issue with:

• Clear description
• Steps to reproduce
• Expected vs actual behavior
• Quartz version and OS

💡 Suggest Features

Have an idea? We'd love to hear it:

• Describe the use case
• Explain the benefit
• Consider the complexity
• Show example syntax

📝 Improve Documentation

Documentation always needs work:

• Fix typos and errors
• Add examples
• Clarify confusing sections
• Translate to other languages

💻 Write Code

Ready to code? Great options:

• Fix open issues
• Add new standard library functions
• Improve error messages
• Optimize performance

Development Workflow

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

2. Make Your Changes

Follow the code style of existing code. Key principles:

• Keep it simple and readable
• Add comments for non-obvious code
• Write tests for new features
• Update documentation if needed

3. Test Your Changes

# Rebuild
bash rebuild_core.sh

# Run tests
./sanity_check.sh
./feature_check.sh

4. Commit

git add .
git commit -m "feat: add frobnicate function to system.string"

Commit message format:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• refactor: Code refactoring
• test: Adding tests
• chore: Build/tooling changes

5. Push and Create PR

git push origin feature/your-feature-name

Then open a Pull Request on GitHub.

Code Structure

quartz/
├── src/core/           # Core implementation
│   ├── lexer.cpp       # Tokenizer
│   ├── parser.cpp      # AST generator
│   ├── runtime.cpp     # Interpreter
│   ├── bytecode.cpp    # Bytecode compiler
│   └── vm.cpp          # Bytecode VM
├── include/core/       # Header files
├── extensions/         # Standard library extensions
│   ├── system_io/      # I/O module
│   ├── system_math/    # Math module
│   └── ...
├── samples/            # Example programs
├── docs/               # Documentation
└── website/            # This website

Adding Standard Library Functions

Adding a new function to an existing module:

// In extensions/system_math/math.cpp

auto myNewFunction = [](const std::vector<Value>& args) -> Value {
// Implementation
return Value(result);
};

reg.registerFunction("system.math.myNewFunction", myNewFunction);

Don't forget to:

• Add documentation
• Add a sample program
• Test both interpreter and bytecode modes

Code Style

C++ Style

• Use C++17 features appropriately
• Prefer auto for obvious types
• Use smart pointers over raw pointers
• Keep functions small and focused
• Use meaningful variable names

Quartz Sample Style

• Use 4 spaces for indentation
• Keep lines under 100 characters
• Add comments explaining the purpose
• Show both simple and advanced usage

Review Process

1. Automated checks: Your PR will run through CI tests
2. Code review: A maintainer will review your changes
3. Feedback: You may be asked to make changes
4. Merge: Once approved, your PR will be merged

Community Guidelines

• Be respectful: Treat everyone with respect
• Be constructive: Focus on improving things
• Be patient: We're all volunteers here
• Be open: Welcome feedback and different perspectives

Getting Help

Stuck? Need guidance? Here's how to get help:

• GitHub Discussions - Ask questions
• GitHub Issues - Report problems
• Read the Architecture documentation
• Study existing code and extensions

🙏 Thank You! Every contribution, no matter how small, helps make Quartz better. We appreciate your time and effort!