Contributing to Veyra

Thank you for your interest in contributing to Veyra! We welcome contributions from everyone, whether you're fixing a bug, adding a feature, or improving documentation.

📋 Table of Contents

Code of Conduct
Getting Started
Development Setup
How to Contribute
Coding Standards
Testing
Pull Request Process
Project Structure

🤝 Code of Conduct

By participating in this project, you agree to:

Be respectful and inclusive
Accept constructive criticism
Focus on what's best for the community
Show empathy towards other community members

🚀 Getting Started

Prerequisites

Rust 1.70+ - Install Rust
Git - For version control
A GitHub account - For submitting contributions

First Time Setup

Fork the repository on GitHub

Clone your fork locally:

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

Add upstream remote:

git remote add upstream https://github.com/k6w/veyra.git

Build the project:

cd compiler
cargo build
cd ../tools
cargo build

Run tests:
```
cargo test
```

💻 Development Setup

Building Components

# Build compiler
cd compiler
cargo build --release

# Build runtime
cd runtime
cargo build --release

# Build tools (REPL, LSP, debugger, etc.)
cd tools
cargo build --release

# Build specific tool
cargo build -p veyra-repl --release

Running Tests

# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

# Run tests for specific package
cargo test -p veyra-compiler

Code Formatting

# Format code
cargo fmt

# Check formatting
cargo fmt -- --check

Linting

# Run clippy
cargo clippy

# Run clippy with all warnings
cargo clippy -- -W clippy::all

🛠️ How to Contribute

Types of Contributions

🐛 Bug Fixes - Fix issues and improve stability
✨ New Features - Add new language features or tools
📝 Documentation - Improve docs, examples, or comments
🧪 Tests - Add or improve test coverage
🎨 Code Quality - Refactoring and optimization
🔧 Tools - Improve developer tools (REPL, LSP, etc.)

Finding Issues to Work On

Check the Issues page
Look for issues labeled:
- good first issue - Great for newcomers
- help wanted - Need community help
- bug - Bug fixes needed
- enhancement - Feature requests

Before Starting Work

Check existing issues - Make sure your idea isn't already being worked on
Create an issue - Discuss your idea before implementing large changes
Get feedback - Wait for maintainer approval on significant features
Claim the issue - Comment on the issue to let others know you're working on it

📝 Coding Standards

Rust Code Style

Follow the Rust API Guidelines
Use cargo fmt for formatting
Use cargo clippy to catch common mistakes
Write idiomatic Rust code

Naming Conventions

// Modules: snake_case
mod parser;
mod lexer;

// Types: PascalCase
struct Token;
enum TokenKind;

// Functions: snake_case
fn parse_expression();
fn tokenize();

// Constants: SCREAMING_SNAKE_CASE
const MAX_DEPTH: usize = 100;

// Variables: snake_case
let token_kind = TokenKind::Identifier;

Documentation

/// Brief description of the function
///
/// # Arguments
///
/// * `input` - Description of input parameter
///
/// # Returns
///
/// Description of return value
///
/// # Examples
///
/// ```
/// let result = function_name(input);
/// ```
pub fn function_name(input: &str) -> Result<String, Error> {
    // Implementation
}

Error Handling

Use Result<T, E> for operations that can fail
Provide meaningful error messages
Use the ? operator for error propagation
Document error conditions

pub fn parse_file(path: &Path) -> Result<Program, ParseError> {
    let content = fs::read_to_string(path)
        .map_err(|e| ParseError::IoError(e))?;
    
    let tokens = tokenize(&content)?;
    parse_program(tokens)
}

🧪 Testing

Writing Tests

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_basic_functionality() {
        let input = "test input";
        let expected = "expected output";
        assert_eq!(function_under_test(input), expected);
    }

    #[test]
    fn test_error_case() {
        let input = "invalid input";
        assert!(function_under_test(input).is_err());
    }
}

Test Coverage

Write tests for new features
Add tests for bug fixes to prevent regressions
Include edge cases and error conditions
Aim for high test coverage

Running Specific Tests

# Run tests for a specific module
cargo test lexer

# Run a specific test
cargo test test_basic_functionality

# Run tests with output
cargo test -- --nocapture

🔄 Pull Request Process

1. Create a Branch

# Create and switch to a new branch
git checkout -b feature/my-new-feature

# Or for bug fixes
git checkout -b fix/issue-123

2. Make Your Changes

Write clean, well-documented code
Follow coding standards
Add tests for new functionality
Update documentation as needed

3. Commit Your Changes

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "Add feature: brief description"

Commit Message Guidelines:

Use present tense ("Add feature" not "Added feature")
Use imperative mood ("Move cursor to..." not "Moves cursor to...")
Limit first line to 72 characters
Reference issues and pull requests

Examples:

Add support for async/await syntax
Fix lexer bug with string escaping (#123)
Update documentation for error handling
Refactor parser for better performance

4. Keep Your Fork Updated

# Fetch upstream changes
git fetch upstream

# Merge upstream changes
git merge upstream/main

5. Push to Your Fork

git push origin feature/my-new-feature

6. Create a Pull Request

Go to your fork on GitHub
Click "Pull Request"
Select your branch
Fill out the PR template:
- Title: Clear, concise description
- Description: What changes were made and why
- Related Issues: Link to related issues
- Testing: How you tested the changes
- Screenshots: If applicable

7. PR Review Process

Maintainers will review your PR
Address feedback and requested changes
Push additional commits to your branch if needed
Once approved, a maintainer will merge your PR

📁 Project Structure

veyra/
├── compiler/              # Core compiler
│   ├── src/
│   │   ├── lexer.rs      # Tokenization
│   │   ├── parser.rs     # AST generation
│   │   ├── ast.rs        # AST definitions
│   │   ├── interpreter.rs # Execution engine
│   │   └── error.rs      # Error types
│   └── Cargo.toml
│
├── runtime/               # Advanced runtime features
│   ├── src/
│   │   ├── garbage_collector.rs
│   │   ├── jit_compiler.rs
│   │   ├── async_runtime.rs
│   │   └── actor_system.rs
│   └── Cargo.toml
│
├── tools/                 # Developer tools
│   ├── repl/             # Interactive REPL
│   ├── lsp/              # Language Server Protocol
│   ├── debugger/         # Debugger
│   ├── linter/           # Code linter
│   └── package_manager/  # Package management
│
├── stdlib/                # Standard library
│   ├── core.vey
│   ├── math.vey
│   ├── string.vey
│   └── collections.vey
│
├── spec/                  # Language specification
│   ├── LANGUAGE_SPEC.md
│   └── GRAMMAR.ebnf
│
├── examples/              # Example programs
├── tests/                 # Test suite
└── docs/                  # Additional documentation

🎯 Areas Needing Contributions

High Priority

Features

Pattern matching enhancements
Type inference improvements
Additional collection types
Async/await optimizations
Package registry implementation

Tools

IDE plugins for other editors
Code formatter improvements
Debugger enhancements
REPL features (autocomplete, syntax highlighting)
Package manager features

💬 Getting Help

Questions? Open a Discussion
Found a bug? Open an Issue
Need guidance? Ask in the issue comments

🙏 Recognition

Contributors will be:

Listed in CONTRIBUTORS.md
Credited in release notes
Recognized in project documentation

Thank you for contributing to Veyra! 🎉

Questions? Feel free to ask in GitHub Discussions

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History