Contribution Guide - source-academy/pie-slang GitHub Wiki

Contributing Guide

Thank you for your interest in contributing to the Pie interpreter! This guide will help you understand how to contribute effectively to the project.

Table of Contents

Getting Started

Prerequisites

  • Node.js (v14.0.0 or higher)
  • npm (v6.0.0 or higher)
  • Git

Setting Up Your Development Environment

  1. Fork the repository on GitHub.
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/pie-slang.git
cd pie-slang
  3. Add the original repository as a remote: 
    git remote add upstream https://github.com/ZhangQixiang123/pie-slang.git
  4. Install dependencies: 
    npm install
  5. Build the project: 
    npm run build
  6. Run tests to verify your setup: 
    npm test

Development Workflow

We follow a feature branch workflow:

  1. Create a new branch for your feature: 
    git checkout -b feature/your-feature-name
  2. Make your changes.
  3. Write tests for your changes.
  4. Run the tests: 
    npm test
  5. Commit your changes with a descriptive commit message.
  6. Push your branch to your fork: 
    git push origin feature/your-feature-name
  7. Create a pull request from your fork to the main repository.

Coding Standards

There is no strict standard, these guidelines are for your references.

General Guidelines

  • Use TypeScript's strict mode.
  • Follow the Single Responsibility Principle.
  • Keep functions and methods small and focused.
  • Use descriptive names for variables, functions, and classes.
  • Comment your code where necessary, especially for complex logic.

TypeScript Guidelines

  • Use explicit type annotations for function parameters and return types.
  • Prefer interfaces over type aliases for object types.
  • Use readonly for immutable properties.
  • Use optional parameters and properties where appropriate.
  • Use union types instead of enums when possible.

Code Formatting

We use Prettier for code formatting. You can format your code with:

npm run format

Linting

We use ESLint to catch errors and enforce code quality. Run the linter with:

npm run lint

Testing

We use Jest for testing. All code should be covered by tests.

Writing Tests

  • Tests should be placed in the __tests__ directory.
  • Test files should be named [component].test.ts.
  • Use descriptive test names that explain what is being tested.
  • Test both successful and error cases.

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run a specific test file
npx jest path/to/test/file.test.ts