Contributing to GGcode Compiler

Thank you for your interest in contributing to the GGcode Compiler! This document provides guidelines and information for contributors.

🚀 Getting Started

Prerequisites

Node.js >= 16.0.0
npm >= 8.0.0
Git
Basic understanding of JavaScript, Node.js, and web development

Development Setup

Fork and Clone

git clone https://github.com/your-username/ggcode-compiler.git
cd ggcode-compiler

Install Dependencies
```
npm install
```

Set Up Environment

cp .env.example .env
# Edit .env with your local configuration

Verify Setup
```
npm run build
npm test
```

🏗️ Project Architecture

Directory Structure

src/
├── client/                 # Client-side code (ES6 modules)
│   ├── js/
│   │   ├── api/           # API client modules
│   │   ├── configurator/  # Configurator system
│   │   ├── editor/        # Editor components
│   │   ├── ui/            # UI components
│   │   ├── visualizer/    # 3D visualization
│   │   └── main.js        # Application entry point
│   └── css/               # Stylesheets
├── server/                # Server-side code (CommonJS)
│   ├── config/            # Configuration management
│   ├── middleware/        # Express middleware
│   ├── routes/            # API routes
│   ├── services/          # Business logic
│   ├── app.js             # Express application
│   └── index.js           # Server entry point
tests/                     # Test suite
├── client/                # Client-side tests
├── server/                # Server-side tests
└── utils/                 # Test utilities

Module System

Client-side: ES6 modules (import/export)
Server-side: CommonJS modules (require/module.exports)
Backward Compatibility: Global exports for HTML onclick handlers

📝 Development Guidelines

Code Style

We use ESLint and Prettier for consistent code formatting:

# Check linting
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

Coding Standards

JavaScript

ES6+ Features: Use modern JavaScript features
Async/Await: Prefer async/await over Promises
Error Handling: Always handle errors appropriately
Documentation: Use JSDoc comments for functions and classes

Client-Side Modules

/**
 * Example client-side module
 */
class ExampleManager {
  constructor() {
    this.initialized = false;
  }

  /**
   * Initialize the manager
   * @param {Object} options - Configuration options
   */
  async initialize(options = {}) {
    // Implementation
  }
}

export default ExampleManager;

Server-Side Modules

/**
 * Example server-side service
 */
class ExampleService {
  constructor() {
    this.config = require('../config');
  }

  /**
   * Process data
   * @param {Object} data - Input data
   * @returns {Promise<Object>} Processed result
   */
  async processData(data) {
    // Implementation
  }
}

module.exports = ExampleService;

Testing

Test Structure

Unit Tests: Test individual functions and classes
Integration Tests: Test API endpoints and service interactions
Client Tests: Test browser-based components

Writing Tests

describe('ExampleService', () => {
  let service;

  beforeEach(() => {
    service = new ExampleService();
  });

  describe('processData', () => {
    it('should process data correctly', async () => {
      const input = { test: 'data' };
      const result = await service.processData(input);
      
      expect(result).toBeDefined();
      expect(result.processed).toBe(true);
    });

    it('should handle errors gracefully', async () => {
      const invalidInput = null;
      
      await expect(service.processData(invalidInput))
        .rejects.toThrow('Invalid input');
    });
  });
});

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- --testPathPattern=example.test.js

🔄 Development Workflow

Branch Strategy

Main Branch: main - Production-ready code
Feature Branches: feature/feature-name - New features
Bug Fixes: fix/bug-description - Bug fixes
Hotfixes: hotfix/critical-fix - Critical production fixes

Commit Messages

We follow Conventional Commits:

type(scope): description

[optional body]

[optional footer]

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples

feat(api): add new compilation endpoint
fix(editor): resolve syntax highlighting issue
docs(readme): update installation instructions
test(compiler): add unit tests for validation

Pull Request Process

Create Feature Branch

git checkout -b feature/your-feature-name

Make Changes
- Write code following our standards
- Add tests for new functionality
- Update documentation as needed
Test Your Changes
```
npm run build
npm test
npm run lint
```

Commit Changes

git add .
git commit -m "feat(scope): description"

Push and Create PR

git push origin feature/your-feature-name

PR Requirements
- Clear description of changes
- Tests pass
- Code review approval
- Documentation updated

🐛 Bug Reports

Before Reporting

Search Existing Issues: Check if the bug is already reported
Reproduce the Bug: Ensure you can consistently reproduce it
Check Latest Version: Verify the bug exists in the latest version

Bug Report Template

## Bug Description
Brief description of the bug

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- OS: [e.g., Windows 10, macOS 12, Ubuntu 20.04]
- Node.js version: [e.g., 16.14.0]
- Browser: [e.g., Chrome 96, Firefox 95]
- GGcode Compiler version: [e.g., 1.0.0]

## Additional Context
Any other relevant information

💡 Feature Requests

Before Requesting

Check Existing Requests: Look for similar feature requests
Consider Scope: Ensure the feature fits the project's goals
Think About Implementation: Consider how it might be implemented

Feature Request Template

## Feature Description
Clear description of the proposed feature

## Use Case
Why is this feature needed? What problem does it solve?

## Proposed Solution
How do you envision this feature working?

## Alternatives Considered
What other approaches have you considered?

## Additional Context
Any other relevant information or mockups

🔧 Development Tasks

Adding New API Endpoints

Create Route Handler

// src/server/routes/example.js
router.get('/api/example', async (req, res) => {
  // Implementation
});

Add Service Logic

// src/server/services/exampleService.js
class ExampleService {
  async processRequest(data) {
    // Business logic
  }
}

Create Client API

// src/client/js/api/example.js
class ExampleAPI extends APIClient {
  async getExample() {
    return this.get('/api/example');
  }
}

Add Tests

// tests/server/routes/example.test.js
// tests/client/api/example.test.js

Adding New UI Components

Create Component Module

// src/client/js/ui/example.js
class ExampleComponent {
  constructor() {
    this.element = null;
  }

  render() {
    // Render logic
  }
}

export default ExampleComponent;

Add Styles

/* src/client/css/components.css */
.example-component {
  /* Styles */
}

Integrate with Main App

// src/client/js/main.js
import ExampleComponent from './ui/example.js';

Add Tests
```
// tests/client/ui/example.test.js
```

📚 Documentation

Code Documentation

JSDoc Comments: Document all public functions and classes
README Updates: Update README for new features
API Documentation: Document new API endpoints
Examples: Provide usage examples

Documentation Standards

/**
 * Process GGcode compilation
 * @param {string} ggcode - The GGcode source to compile
 * @param {Object} options - Compilation options
 * @param {boolean} options.validate - Whether to validate syntax
 * @param {number} options.timeout - Compilation timeout in ms
 * @returns {Promise<Object>} Compilation result
 * @throws {Error} If compilation fails
 * @example
 * const result = await compiler.compile('G1 X10 Y10', { validate: true });
 */
async compile(ggcode, options = {}) {
  // Implementation
}

🚀 Release Process

Version Numbering

We follow Semantic Versioning:

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes (backward compatible)

Release Checklist

Update Version: Update version in package.json
Update Changelog: Add new version to CHANGELOG.md
Run Tests: Ensure all tests pass
Build: Create production build
Tag Release: Create Git tag
Deploy: Deploy to production

🤝 Community

Communication

GitHub Issues: Bug reports and feature requests
GitHub Discussions: Questions and general discussion
Pull Requests: Code contributions

Code of Conduct

Be Respectful: Treat all contributors with respect
Be Constructive: Provide helpful feedback
Be Patient: Remember that everyone is learning
Be Inclusive: Welcome contributors of all backgrounds

📞 Getting Help

Resources

Documentation: Check the README and inline documentation
Examples: Look at existing code for patterns
Tests: Examine test files for usage examples
Issues: Search existing issues for solutions

Asking Questions

When asking for help:

Be Specific: Describe exactly what you're trying to do
Provide Context: Include relevant code and error messages
Show Effort: Explain what you've already tried
Be Patient: Allow time for responses

🎯 Areas for Contribution

High Priority

Bug Fixes: Fix reported issues
Test Coverage: Improve test coverage
Documentation: Enhance documentation
Performance: Optimize performance bottlenecks

Medium Priority

New Features: Implement requested features
UI/UX Improvements: Enhance user experience
Code Quality: Refactor and improve code quality
Accessibility: Improve accessibility compliance

Low Priority

Examples: Add more example files
Tooling: Improve development tools
Integrations: Add third-party integrations
Localization: Add multi-language support

📄 License

By contributing to GGcode Compiler, you agree that your contributions will be licensed under the ISC License.

Thank you for contributing to GGcode Compiler! Your efforts help make this project better for everyone. 🙏

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History