Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
306 lines (217 loc) · 6.09 KB

CONTRIBUTING.md

File metadata and controls

306 lines (217 loc) · 6.09 KB

Contributing to Cheatron

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

📋 Table of Contents

📜 Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

🚀 Getting Started

Prerequisites

  • Node.js >= 20.0.0
  • npm >= 10.0.0
  • Git
  • Windows (for native functionality testing)

Setup Development Environment

  1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/cheatron-core.git
cd cheatron-core
  1. Install dependencies
npm install
  1. Build all packages
npm run build
  1. Run tests
npm test

🔄 Development Workflow

1. Create a Branch

git checkout -b feat/your-feature-name
# or
git checkout -b fix/your-bug-fix

Branch naming convention:

  • feat/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • refactor/ - Code refactoring
  • test/ - Test additions/changes
  • chore/ - Maintenance tasks

2. Make Changes

  • Write clean, readable code
  • Follow existing code style
  • Add tests for new functionality
  • Update documentation as needed

3. Test Your Changes

# Run linter
npm run lint

# Run type check
npm run typecheck

# Run tests
npm test

# Check code formatting
npm run format:check

4. Commit Your Changes

We use Conventional Commits:

git add .
git commit -m "feat(native): Add memory pattern scanning"

Commit message format:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Test additions/changes
  • build: Build system changes
  • ci: CI configuration changes
  • chore: Other changes

Scopes:

  • core, native, nthread, capstone, keystone, log, native-bindings, win32-ext
  • deps: Dependency updates
  • workspace: Workspace/monorepo changes

5. Push and Create PR

git push origin feat/your-feature-name

Then create a Pull Request on GitHub.

🔀 Pull Request Process

  1. Update Documentation: Ensure documentation reflects your changes
  2. Add Tests: New features should include tests
  3. Update Changelog: Add entry to CHANGELOG.md if applicable
  4. Self-Review: Review your own PR first
  5. Request Review: Request review from maintainers
  6. Address Feedback: Respond to review comments
  7. Squash Commits: Clean up commit history if requested

PR Title Format

Use the same format as commit messages:

feat(native): Add memory pattern scanning

PR Description Template

The PR template is automatically loaded. Fill in all sections:

  • Description of changes
  • Type of change
  • Related issues
  • Checklist items
  • Screenshots (if applicable)

📏 Coding Standards

TypeScript

  • Use TypeScript strict mode
  • Prefer const over let
  • Use meaningful variable names
  • Add JSDoc comments for public APIs
  • Avoid any type when possible

Code Style

  • Indentation: 2 spaces
  • Quotes: Single quotes for strings
  • Semicolons: Always use them
  • Line length: Max 80 characters (enforced by Prettier)

File Organization

// 1. Imports
import { external } from 'package';
import { internal } from './internal';

// 2. Types/Interfaces
export interface MyInterface {
  // ...
}

// 3. Constants
const CONSTANT_VALUE = 42;

// 4. Implementation
export class MyClass {
  // ...
}

Naming Conventions

  • Files: kebab-case (memory-scanner.ts)
  • Classes: PascalCase (MemoryScanner)
  • Functions: camelCase (scanPattern)
  • Constants: UPPER_SNAKE_CASE (MAX_BUFFER_SIZE)
  • Private members: prefix with _ (_privateMethod)

🧪 Testing Guidelines

Writing Tests

  • Use descriptive test names
  • Follow AAA pattern (Arrange, Act, Assert)
  • Test edge cases
  • Mock external dependencies
  • Aim for >70% code coverage

Test Structure

import { describe, test, expect } from 'vitest';

describe('MemoryScanner', () => {
  describe('scanPattern', () => {
    test('should find pattern in memory', () => {
      // Arrange
      const scanner = new MemoryScanner();

      // Act
      const result = scanner.scanPattern('48 8B 05');

      // Assert
      expect(result).toBeDefined();
    });

    test('should return null for invalid pattern', () => {
      const scanner = new MemoryScanner();
      const result = scanner.scanPattern('INVALID');
      expect(result).toBeNull();
    });
  });
});

Running Tests

# All tests
npm test

# Specific package
npm test -w @cheatron/native

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

🔍 Code Review Checklist

Before requesting review, ensure:

  • Code follows project style guidelines
  • Tests are included and passing
  • Documentation is updated
  • No console.log or debug code
  • Type safety is maintained
  • Error handling is appropriate
  • Performance considerations addressed
  • Security implications considered

📦 Publishing (Maintainers Only)

We use Changesets for version management:

# Create a changeset
npm run changeset

# Version packages
npm run version

# Publish to npm
npm run release

💡 Questions?

  • Open an issue for bug reports or feature requests
  • Join our Discord for real-time discussion
  • Check existing issues before creating new ones

🙏 Thank You!

Your contributions make Cheatron better for everyone. We appreciate your time and effort!