Skip to content

contributing

Jump to bottom
Mile Shi edited this page May 26, 2025 · 2 revisions

Contributing Guidelines

Welcome to the Intelligent IDE project! We appreciate your interest in contributing to our educational collaboration platform. This guide will help you get started with contributing code, documentation, and improvements.

Getting Started

Prerequisites

Before contributing, ensure you have:

  • ✅ Development Environment: Set up following our Development Setup Guide
  • ✅ Git Knowledge: Basic understanding of Git workflows
  • ✅ Code Standards: Familiarity with our coding conventions
  • ✅ Testing: Understanding of our testing practices

Project Structure

intelligent-ide/
├── frontend/                 # VS Code extension
│   ├── src/                 # TypeScript source code
│   ├── package.json         # Extension manifest
│   └── tests/               # Frontend tests
├── backend/                 # FastAPI backend
│   ├── app/                 # Python application code
│   ├── requirements.txt     # Python dependencies
│   └── tests/               # Backend tests
├── docs/                    # Documentation
├── scripts/                 # Build and deployment scripts
└── docker-compose.yml       # Development containers

Development Workflow

1. Fork and Clone

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/intelligent-ide.git
cd intelligent-ide

# Add upstream remote
git remote add upstream https://github.com/intelligent-ide/intelligent-ide.git

2. Create Feature Branch

# Update main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

3. Make Changes

Follow our development guidelines:

  • Write clean, well-documented code
  • Follow existing code style and patterns
  • Add tests for new functionality
  • Update documentation as needed

4. Test Your Changes

# Run frontend tests
cd frontend
npm test

# Run backend tests
cd backend
pytest

# Run integration tests
npm run test:integration

5. Submit Pull Request

# Commit your changes
git add .
git commit -m "feat: add new collaboration feature"

# Push to your fork
git push origin feature/your-feature-name

# Create pull request on GitHub

### ProjectOverview.md
```markdown
<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/ProjectOverview.md -->
# Project Overview

## Project Goals
- Define the main objectives of the project.
- Outline the expected outcomes and deliverables.

## Technologies Used
- List the technologies and tools that will be used in the project (e.g., programming languages, frameworks, libraries).

GettingStarted.md

<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/GettingStarted.md -->
# Getting Started

## Prerequisites
- List any software or tools that need to be installed before starting.
  
## Installation Instructions
1. Step-by-step instructions on how to set up the project locally.
2. Include commands and code snippets as necessary.

TeamMembers.md

<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/TeamMembers.md -->
# Team Members

| Name          | Role               | Contact Information |
|---------------|--------------------|---------------------|
| Alice Smith   | Project Manager     | team-lead@intelligent-ide.project    |
| Bob Johnson   | Lead Developer      | developer@intelligent-ide.project      |
| Carol White   | UX/UI Designer      | designer@intelligent-ide.project    |

MeetingNotes.md

<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/MeetingNotes.md -->
# Meeting Notes

## [Date of Meeting]
- Summary of discussions
- Action items
- Next meeting date

Resources.md

<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/Resources.md -->
# Resources

- Links to relevant documentation, tutorials, and articles.
- Any other resources that may be helpful for team members.

FAQs.md

<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/FAQs.md -->
# Frequently Asked Questions

## Question 1
- Answer to question 1.

## Question 2
- Answer to question 2.

Additional Tips

  • Encourage team members to contribute to the wiki by adding their own sections or updating existing ones.
  • Regularly review and update the content to ensure it remains relevant and useful.
  • Consider using tags or categories for easier navigation if the wiki grows large.

Feel free to modify the structure and content to better fit your team's needs!

Code Standards

Frontend (TypeScript)

Code Style

// Use descriptive names and proper TypeScript types
interface CourseData {
  id: string;
  name: string;
  students: Student[];
}

// Use async/await for asynchronous operations
async function fetchCourseData(courseId: string): Promise<CourseData> {
  try {
    const response = await api.get(`/courses/${courseId}`);
    return response.data;
  } catch (error) {
    logger.error('Failed to fetch course data', { courseId, error });
    throw error;
  }
}

// Use proper error handling
class CourseService {
  async createCourse(courseData: CreateCourseRequest): Promise<Course> {
    if (!courseData.name?.trim()) {
      throw new ValidationError('Course name is required');
    }
    
    return await this.apiClient.post('/courses', courseData);
  }
}

File Organization

// services/courseService.ts
export class CourseService {
  // Service implementation
}

// types/course.ts
export interface Course {
  // Type definitions
}

// utils/validation.ts
export function validateCourseData(data: any): boolean {
  // Utility functions
}

Backend (Python)

Code Style

# Use type hints and proper naming conventions
from typing import List, Optional
from fastapi import HTTPException, status

class CourseService:
    """Service for managing course operations."""
    
    async def create_course(
        self, 
        course_data: CreateCourseRequest,
        user_id: str
    ) -> Course:
        """Create a new course with the given data."""
        # Validate input
        if not course_data.name.strip():
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST,
                detail="Course name is required"
            )
        
        # Create course
        course = Course(**course_data.dict(), instructor_id=user_id)
        await self.repository.save(course)
        
        logger.info(f"Created course {course.id} for user {user_id}")
        return course

API Design

# routers/courses.py
from fastapi import APIRouter, Depends, HTTPException
from app.services.course_service import CourseService

router = APIRouter(prefix="/courses", tags=["courses"])

@router.post("/", response_model=CourseResponse)
async def create_course(
    course_data: CreateCourseRequest,
    current_user: User = Depends(get_current_user),
    course_service: CourseService = Depends()
) -> CourseResponse:
    """Create a new course."""
    course = await course_service.create_course(course_data, current_user.id)
    return CourseResponse.from_orm(course)

Testing Guidelines

Frontend Testing

Unit Tests

// tests/services/courseService.test.ts
import { CourseService } from '../../src/services/courseService';
import { mockApiClient } from '../mocks/apiClient';

describe('CourseService', () => {
  let courseService: CourseService;
  
  beforeEach(() => {
    courseService = new CourseService(mockApiClient);
  });
  
  describe('createCourse', () => {
    it('should create course with valid data', async () => {
      const courseData = {
        name: 'Test Course',
        description: 'Test Description'
      };
      
      mockApiClient.post.mockResolvedValue({ data: { id: '123', ...courseData } });
      
      const result = await courseService.createCourse(courseData);
      
      expect(result.id).toBe('123');
      expect(result.name).toBe('Test Course');
    });
    
    it('should throw error for invalid data', async () => {
      const courseData = { name: '', description: 'Test' };
      
      await expect(courseService.createCourse(courseData))
        .rejects.toThrow('Course name is required');
    });
  });
});

Backend Testing

Unit Tests

# tests/services/test_course_service.py
import pytest
from unittest.mock import AsyncMock, MagicMock
from app.services.course_service import CourseService
from app.models.course import Course

@pytest.fixture
def course_service():
    repository = AsyncMock()
    return CourseService(repository)

@pytest.mark.asyncio
async def test_create_course_success(course_service):
    # Arrange
    course_data = CreateCourseRequest(name="Test Course", description="Test")
    user_id = "user_123"
    
    # Act
    result = await course_service.create_course(course_data, user_id)
    
    # Assert
    assert result.name == "Test Course"
    assert result.instructor_id == user_id
    course_service.repository.save.assert_called_once()

Documentation Guidelines

Code Documentation

TypeScript Documentation

/**
 * Service for managing course operations and data.
 * 
 * @example
 * ```typescript
 * const courseService = new CourseService(apiClient);
 * const course = await courseService.createCourse({
 *   name: "CS101",
 *   description: "Introduction to Programming"
 * });
 * ```
 */
export class CourseService {
  /**
   * Creates a new course with the provided data.
   * 
   * @param courseData - The course data to create
   * @returns Promise that resolves to the created course
   * @throws {ValidationError} When course data is invalid
   * @throws {ApiError} When the API request fails
   */
  async createCourse(courseData: CreateCourseRequest): Promise<Course> {
    // Implementation...
  }
}

Pull Request Guidelines

PR Title Format

Use conventional commit format:

  • feat: add new collaboration features
  • fix: resolve file sync issues
  • docs: update API documentation
  • test: add unit tests for course service
  • refactor: improve error handling

PR Description Template

## Description
Brief description of the changes made.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)  
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review of code completed
- [ ] Code is properly documented
- [ ] Tests pass locally
- [ ] No new linting errors introduced

Review Process

  1. Automated Checks: All CI/CD checks must pass
  2. Code Review: At least one team member review required
  3. Testing: Verify all tests pass and functionality works
  4. Documentation: Ensure docs are updated for new features

Community Guidelines

Code of Conduct

  • Be respectful and inclusive
  • Provide constructive feedback
  • Help newcomers and answer questions
  • Follow project guidelines and standards

Communication

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: General questions and discussions
  • Pull Requests: Code reviews and implementation discussions

Getting Help

Resources

Contact

  • Maintainers: Check team member information in main wiki
  • Community: Use GitHub issues for questions and discussions
  • Issues: Create GitHub issues for bugs and features

Thank you for contributing to the Intelligent IDE project! Your efforts help create better educational experiences for students and instructors worldwide. 🎓💻

🏠 Home

📖 User Guide

🛠️ Developer Guide

⭐ Features

📚 Tutorials

Clone this wiki locally