Contributing Guidelines

How to contribute to the Aurora project

Thank you for your interest in contributing to Aurora! This guide will help you understand our contribution process and standards.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [e-mail].

Getting Started

Before contributing, familiarize yourself with:

• The README for project overview
• The Development Setup guide
• The Architecture Deep Dive
• The AGENTS.md for agent-specific guidelines

Types of Contributions

We welcome various types of contributions:

• Bug fixes: Fix issues in existing functionality
• New features: Add new capabilities or integrations
• Documentation: Improve guides, API docs, code comments
• Performance: Optimize code or database queries
• Tests: Add or improve test coverage
• Refactoring: Improve code structure without changing behavior

Before You Start

1. Check existing issues: Search the issue tracker to see if your bug/feature is already being discussed
2. Discuss major changes: For significant changes, open an issue first to discuss your approach
3. Update your fork: Make sure your fork is up to date with the upstream repository
4. Create a feature branch: Always work in a feature branch, never directly on main

Branch Naming Convention

Use descriptive branch names with the following prefixes:

Prefix	Purpose	Example
feature/	New features or enhancements	feature/add-aws-cost-optimization
bugfix/	Bug fixes	bugfix/fix-gcp-auth-error
hotfix/	Urgent production fixes	hotfix/security-patch-vault
docs/	Documentation updates	docs/update-kubernetes-guide
refactor/	Code refactoring	refactor/cleanup-db-utils
test/	Adding or updating tests	test/add-connector-tests
chore/	Maintenance, dependencies	chore/update-dependencies

Naming rules:

• Use lowercase
• Separate words with hyphens
• Be descriptive but concise

Development Workflow

1. Update Your Fork

Sync your fork with the latest changes:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

2. Create a Feature Branch

Create a new branch for your work:

git checkout -b feature/your-feature-name

3. Make Your Changes

Follow these guidelines:

• Write clear commit messages: Use present tense (“Add feature” not “Added feature”)
• Follow code style: See Code Style Guidelines below
• Add tests: Include tests for new functionality when applicable
• Update documentation: Update relevant docs for your changes
• Keep commits focused: Each commit should represent a logical change

4. Test Your Changes

Test your changes locally:

# Start development environment
make dev

# Run frontend linter
cd client && npm run lint

# Check backend logs for errors
make logs

5. Commit Your Changes

Commit with clear, descriptive messages:

git add .
git commit -m "Add feature: description of your changes"

Good commit messages:

• “Add AWS cost optimization recommendations”
• “Fix GCP authentication timeout error”
• “Refactor database connection pooling”
• “Update Kubernetes deployment guide”

Bad commit messages:

• “Fix bug”
• “Updates”
• “WIP”
• “asdf”

6. Push to Your Fork

Push your branch to your GitHub fork:

git push origin feature/your-feature-name

7. Open a Pull Request

1. Go to the main Aurora repository
2. You should see a prompt to create a PR from your recently pushed branch
3. Click “Compare & pull request”
4. Ensure the PR targets the main branch of the upstream repository
5. Fill out the PR template with:
   • Clear description of changes
   • Related issue numbers (e.g., “Fixes #123”)
   • Screenshots for UI changes
   • Testing steps to verify your changes

PR Title Format:

• Use present tense
• Be descriptive but concise
• Examples:
  • “Add AWS EC2 instance rightsizing recommendations”
  • “Fix Vault token refresh on expiration”
  • “Update GCP connector to use Application Default Credentials”

8. Address Review Feedback

Respond to reviewer comments and make requested changes:

# Make changes based on feedback
git add .
git commit -m "Address review feedback: improve error handling"
git push origin feature/your-feature-name

New commits will automatically appear in the PR.

9. After Your PR is Merged

Once your PR is approved and merged:

# Switch to main branch
git checkout main

# Pull latest changes
git fetch upstream
git merge upstream/main
git push origin main

# Delete feature branch (local)
git branch -d feature/your-feature-name

# Delete feature branch (remote)
git push origin --delete feature/your-feature-name

Code Style Guidelines

General Principles

• Keep functions small and focused (single responsibility)
• Avoid deep nesting (max 3-4 levels)
• Write self-documenting code (clear variable/function names)
• Add comments for complex logic only
• No commented-out code in PRs
• No emojis in code or logs

Python (Backend)

Naming Conventions:

# snake_case for functions, variables, files
def calculate_total_cost(resources):
    total_cost = 0
    return total_cost

# PascalCase for classes
class CloudConnector:
    pass

# UPPER_CASE for constants
MAX_RETRIES = 3
DEFAULT_TIMEOUT = 30

Import Organization:

# Standard library
import os
import sys
from typing import List, Dict

# Third-party packages
import boto3
from flask import Flask, request
from langchain_core.messages import HumanMessage

# Local modules
from utils.db.db_utils import connect_to_db
from connectors.aws_connector.aws_client import AWSClient

Error Handling:

import logging

logger = logging.getLogger(__name__)

try:
    result = perform_operation()
except SpecificException as e:
    logger.error(f"Operation failed: {e}")
    raise
except Exception as e:
    logger.exception("Unexpected error occurred")
    raise

Database Queries:

from utils.db.connection_pool import db_pool

def get_user_projects(user_id: str) -> List[Dict]:
    conn = db_pool.get_connection()
    try:
        cursor = conn.cursor()
        cursor.execute(
            "SELECT * FROM projects WHERE user_id = %s",
            (user_id,)
        )
        return cursor.fetchall()
    finally:
        cursor.close()
        db_pool.release_connection(conn)

Flask Routes:

from flask import Blueprint, jsonify, request
from utils.auth.stateless_auth import token_required

blueprint = Blueprint('projects', __name__)

@blueprint.route('/api/projects', methods=['GET'])
@token_required
def list_projects(current_user):
    try:
        projects = get_user_projects(current_user['id'])
        return jsonify({"projects": projects}), 200
    except Exception as e:
        logger.error(f"Error listing projects: {e}")
        return jsonify({"error": "Failed to list projects"}), 500

TypeScript (Frontend)

Naming Conventions:

// camelCase for variables and functions
const projectId = "123";
function fetchProjects() { }

// PascalCase for components and types
function ProjectCard() { }
interface UserProject { }
type ProjectStatus = "active" | "archived";

// UPPER_CASE for constants
const MAX_PROJECTS = 100;
const API_BASE_URL = process.env.NEXT_PUBLIC_BACKEND_URL;

React Components:

import { useState, useEffect } from "react";
import { Card } from "@/components/ui/card";

interface ProjectCardProps {
  projectId: string;
  onSelect?: (id: string) => void;
}

export function ProjectCard({ projectId, onSelect }: ProjectCardProps) {
  const [loading, setLoading] = useState(false);
  
  useEffect(() => {
    // Fetch project data
  }, [projectId]);
  
  return (
    <Card className="p-4">
      {/* Component content */}
    </Card>
  );
}

API Calls:

import { getSession } from "next-auth/react";

async function fetchProjects() {
  try {
    const session = await getSession();
    const response = await fetch(
      `${process.env.NEXT_PUBLIC_BACKEND_URL}/api/projects`,
      {
        headers: {
          "Authorization": `Bearer ${session?.accessToken}`,
          "Content-Type": "application/json",
        },
      }
    );
    
    if (!response.ok) {
      throw new Error("Failed to fetch projects");
    }
    
    return await response.json();
  } catch (error) {
    console.error("Error fetching projects:", error);
    throw error;
  }
}

Path Aliases:

// Use @/ for src imports
import { Button } from "@/components/ui/button";
import { useAuth } from "@/lib/auth";
import type { Project } from "@/types/project";

Linting

Run linters before committing:

# Frontend linting
cd client && npm run lint

# Frontend lint with auto-fix
cd client && npm run lint -- --fix

Docker Compose Files

Important: Always update both Docker Compose files together:

• docker-compose.yaml (development)
• docker-compose.prod-local.yml (production)

When adding environment variables:

1. Add to both files
2. Add to .env.example with documentation
3. Update relevant documentation

The CI pipeline will automatically validate env var consistency.

Environment Variables

When adding new environment variables:

1. Add to .env.example with clear documentation:

# New feature flag
ENABLE_COST_OPTIMIZATION=false

2. Update Docker Compose files (both dev and prod):

environment:
  - ENABLE_COST_OPTIMIZATION=${ENABLE_COST_OPTIMIZATION:-false}

3. Update documentation in relevant guides

Reporting Bugs

When reporting bugs, include:

1. Description: Clear description of the bug
2. Steps to Reproduce: Detailed steps to reproduce the issue
3. Expected Behavior: What you expected to happen
4. Actual Behavior: What actually happened
5. Environment:
   • OS and version
   • Docker version
   • Browser (for frontend issues)
   • Relevant .env configuration
6. Logs: Relevant error messages or logs
7. Screenshots: If applicable

Use the issue tracker with the bug label.

Suggesting Features

When suggesting features, include:

1. Use Case: Describe the problem you’re trying to solve
2. Proposed Solution: Your suggested approach
3. Alternatives: Other solutions you’ve considered
4. Additional Context: Any other relevant information

Open an issue with the enhancement label.

Pull Request Guidelines

• Keep PRs focused: One feature/fix per PR
• Write clear descriptions: Explain what and why, not just how
• Link related issues: Use “Fixes #123” to auto-close issues
• Add screenshots: For UI changes, include before/after screenshots
• Update documentation: Keep docs in sync with code changes
• Be responsive: Respond to review feedback promptly
• Be patient: Maintainers review PRs as time allows

Questions?

If you have questions about contributing:

• Open a GitHub Discussion
• Contact maintainers: [e-mail]
• Check existing issues and documentation

License

By contributing to Aurora, you agree that your contributions will be licensed under the Apache License 2.0. See LICENSE for details.

Thank You!

Thank you for contributing to Aurora and helping make cloud infrastructure management more accessible!

Next Steps

Development Setup

Set up your local development environment

Architecture

Learn about Aurora’s architecture

Testing Guide

Write and run tests for your changes