Contributing to MonkeyScript

Thank you for your interest in contributing to MonkeyScript! This document provides guidelines and instructions for contributing

Getting Started

Prerequisites

• .NET 6.0 SDK or higher
• Git
• A C# IDE (Visual Studio 2022, VS Code with C# extension, or JetBrains Rider)

Setting Up Your Development Environment

1. Fork the repository

   # Click the 'Fork' button on GitHub, then clone your fork
   git clone https://github.com/ownedalaa/MonkeyScript.git # Or alternatively use SSH
   cd MonkeyScript
   

2. Add the upstream remote

   git remote add upstream https://github.com/ownedalaa/MonkeyScript.git
   

3. Create a development branch

   git checkout -b feature/your-feature-name
   

Code Style Rules

General Guidelines

• Use C# naming conventions

  • PascalCase for public members, classes, methods
  • camelCase for local variables, parameters
  • _camelCase for private fields (with underscore prefix)

• Keep methods focused - Each method should do one thing well

• Avoid deep nesting - Refactor complex conditions into helper methods

• Comment wisely - Explain why, not what

Specific Patterns Used in MonkeyScript

1. Private Helper Methods

Prefix internal parsing/lexing helpers with double underscore:

private string __Num() { /* ... */ }
private string __Identifier() { /* ... */ }
private Keywords.Type __Keyword(string word) { /* ... */ }

2. Parser Methods

• Use Parse prefix for methods that construct AST nodes
• Use descriptive names: ParseExpression(), ParseStatement(), ParseBlockStatement()

private Expression ParseExpression() { /* ... */ }
private Statement ParseIfStatement() { /* ... */ }

3. Token Handling

// Check and advance
private bool Match(TokenType type) { /* ... */ }

// Require and advance
private Token Consume(TokenType type, string message) { /* ... */ }

// Look ahead without advancing
private Token Peek(int n) { /* ... */ }

4. Error Messages

• Be descriptive and helpful
• Include expected vs actual when relevant
• Use string interpolation for dynamic messages

throw new Exception($"expected ';' after statement");
throw new Exception($"unexpected token {CurrentToken().value}");

File Organization

1. Using statements (grouped and sorted)
2. Namespace declaration
3. Class declaration
4. Fields
5. Constructors
6. Public methods
7. Private methods

Submitting Pull Requests

Before Submitting

1. Format your code

   dotnet format
   

2. Update documentation if you've changed:

   • Public APIs
   • Language syntax
   • Configuration options

PR Guidelines

1. Create a focused PR

   • One feature or fix per PR
   • Keep changes minimal and relevant

2. Write a clear title

   Good: "Add support for string concatenation operator"
   Bad: "Updates"
   

3. Describe your changes

   ## Description
   Adds the '+' operator for string concatenation.
   
   ## Changes
   - Modified Lexer to handle string literals
   - Updated Evaluator to concatenate strings with '+'
   - Added tests for string operations
   
   Closes #42
   

4. Reference issues

   • Use "Fixes #123" or "Closes #123" in description
   • Link related issues

PR Review Process

1. Automated checks will run (build, tests)
2. A maintainer will review your code
3. Address any feedback or requested changes
4. Once approved, your PR will be merged

Commit Messages

Use clear, descriptive commit messages:

Good:
- "Add while loop support to parser"
- "Fix scope resolution in nested functions"
- "Refactor Evaluator to use visitor pattern"

Bad:
- "fix bug"
- "updates"
- "wip"

Development Workflow

Typical Contribution Flow

# 1. Sync with upstream
git checkout main
git pull upstream main

# 2. Create feature branch
git checkout -b feature/my-new-feature

# 3. Make changes and commit
git add .
git commit -m "Add my new feature"

# 4. Push to your fork
git push origin feature/my-new-feature

# 5. Create PR on GitHub

Keeping Your Fork Updated

# Fetch upstream changes
git fetch upstream

# Merge into your main branch
git checkout main
git merge upstream/main

# Update your feature branch
git checkout feature/my-feature
git rebase main

Areas for Contribution

Good First Issues

• Adding new operators (modulo %, power **)
• Improving error messages
• Adding documentation examples
• Writing additional tests

Intermediate Issues

• String literal support
• Array/list data structures
• More complex control flow (break, continue)
• Standard library functions

Advanced Issues

• Garbage collection
• Optimization passes
• Debugger support
• IDE integration

Questions?

• Open an issue for bug reports or feature requests
• Tag issues with question for general questions
• Check existing issues before creating new ones

Recognition

Contributors will be acknowledged in:

• The project README
• Release notes
• GitHub contributors page

Thank you for contributing to MonkeyScript! 🎉