Skip to content

Contributing Guide

This guide outlines how to contribute to the AIDDDMAP project, including development setup, coding standards, and submission guidelines.

Getting Started

1. Development Setup

Prerequisites

requirements:
  node: ">=16.0.0"
  npm: ">=7.0.0"
  git: ">=2.0.0"
  docker: ">=20.10.0"
  docker-compose: ">=2.0.0"

Environment Setup

# Clone repository
git clone https://github.com/yourusername/aidddmap.git
cd aidddmap

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Start development environment
docker-compose up -d

2. Project Structure

Directory Layout

aidddmap/
├── src/
│   ├── api/          # API endpoints
│   ├── core/         # Core functionality
│   ├── lib/          # Shared libraries
│   ├── types/        # TypeScript types
│   └── utils/        # Utility functions
├── tests/
│   ├── unit/         # Unit tests
│   ├── integration/  # Integration tests
│   └── e2e/          # End-to-end tests
├── docs/             # Documentation
└── scripts/          # Build and utility scripts

Development Process

1. Branching Strategy

Branch Naming

interface BranchNaming {
  feature: "feature/description";
  bugfix: "bugfix/issue-number";
  hotfix: "hotfix/description";
  release: "release/version";
}

Git Workflow

# Create feature branch
git checkout -b feature/new-feature

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push changes
git push origin feature/new-feature

2. Coding Standards

TypeScript Style Guide

// Use interfaces for object definitions
interface User {
  id: string;
  name: string;
  email: string;
}

// Use type for unions/intersections
type UserRole = "admin" | "user" | "guest";

// Use async/await
async function fetchUser(id: string): Promise<User> {
  try {
    return await db.users.findUnique({ where: { id } });
  } catch (error) {
    throw new Error(`Failed to fetch user: ${error.message}`);
  }
}

Code Formatting

{
  "prettier": {
    "semi": true,
    "singleQuote": true,
    "trailingComma": "es5",
    "printWidth": 80,
    "tabWidth": 2
  }
}

3. Testing Guidelines

Test Structure

describe("UserService", () => {
  describe("createUser", () => {
    it("should create a new user", async () => {
      // Arrange
      const userData = {
        name: "Test User",
        email: "test@example.com",
      };

      // Act
      const user = await userService.createUser(userData);

      // Assert
      expect(user).toHaveProperty("id");
      expect(user.name).toBe(userData.name);
    });

    it("should throw on duplicate email", async () => {
      // Arrange, Act, Assert
      await expect(userService.createUser(existingUserData)).rejects.toThrow();
    });
  });
});

Coverage Requirements

coverage_thresholds:
  statements: 80
  branches: 80
  functions: 80
  lines: 80

Submission Guidelines

1. Pull Requests

PR Template

## Description

Brief description of changes

## Type of change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Checklist

- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Changelog updated
- [ ] PR is linked to issue

Review Process

review_steps:
  1: "Code review by maintainers"
  2: "CI checks pass"
  3: "Documentation review"
  4: "Final approval"
  5: "Merge"

2. Documentation

Documentation Standards

interface DocumentationRequirements {
  code: {
    inline: boolean; // Function and class documentation
    jsdoc: boolean; // JSDoc for public APIs
    examples: boolean; // Usage examples
  };
  markdown: {
    structure: boolean; // Consistent structure
    links: boolean; // Working links
    images: boolean; // Optimized images
  };
}

API Documentation

/**
 * Creates a new user in the system
 * @param {CreateUserDto} userData - The user data
 * @returns {Promise<User>} The created user
 * @throws {ValidationError} If data is invalid
 * @throws {DuplicateError} If email exists
 */
async function createUser(userData: CreateUserDto): Promise<User> {
  // Implementation
}

3. Issue Management

Issue Template

issue_template:
  bug_report:
    - Description
    - Steps to reproduce
    - Expected behavior
    - Actual behavior
    - Environment details

  feature_request:
    - Problem description
    - Proposed solution
    - Alternative solutions
    - Additional context

Issue Labels

interface IssueLabels {
  type: ["bug", "feature", "documentation", "question"];
  priority: ["high", "medium", "low"];
  status: ["triage", "in-progress", "review", "blocked"];
  scope: ["frontend", "backend", "api", "security"];
}

Best Practices

1. Code Quality

Clean Code Principles

  • Write self-documenting code
  • Follow SOLID principles
  • Keep functions small and focused
  • Use meaningful names

Security Guidelines

  • Validate all inputs
  • Sanitize data
  • Use parameterized queries
  • Follow security best practices

2. Performance

Optimization Guidelines

  • Use appropriate data structures
  • Optimize database queries
  • Implement caching
  • Profile performance

Resource Management

  • Handle memory efficiently
  • Close connections properly
  • Use connection pooling
  • Implement proper error handling

3. Collaboration

Communication

  • Be respectful and professional
  • Provide constructive feedback
  • Ask questions when unclear
  • Share knowledge

Team Work

  • Help other contributors
  • Review pull requests
  • Participate in discussions
  • Follow project guidelines

Next Steps

  1. Set up your development environment
  2. Read the coding standards
  3. Review testing guidelines
  4. Check submission process
  5. Start contributing

Support

Need help contributing?