> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/Arvo-AI/aurora/blob/main/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [info@arvoai.ca](mailto:info@arvoai.ca).

## Getting Started

Before contributing, familiarize yourself with:

* The [README](https://github.com/Arvo-AI/aurora) for project overview
* The [Development Setup](/development/setup) guide
* The [Architecture Deep Dive](/development/architecture-deep-dive)
* The [AGENTS.md](https://github.com/Arvo-AI/aurora/blob/main/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](https://github.com/Arvo-AI/aurora/issues) 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:

```bash theme={null}
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:

```bash theme={null}
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](#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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
git push origin feature/your-feature-name
```

### 7. Open a Pull Request

1. Go to the [main Aurora repository](https://github.com/Arvo-AI/aurora)
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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**:

```python theme={null}
# 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**:

```python theme={null}
# 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**:

```python theme={null}
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**:

```python theme={null}
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**:

```python theme={null}
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**:

```typescript theme={null}
// 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**:

```typescript theme={null}
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**:

```typescript theme={null}
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**:

```typescript theme={null}
// 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:

```bash theme={null}
# 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:

```bash theme={null}
# New feature flag
ENABLE_COST_OPTIMIZATION=false
```

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

```yaml theme={null}
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](https://github.com/Arvo-AI/aurora/issues) 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](https://github.com/Arvo-AI/aurora/discussions)
* Contact maintainers: [info@arvoai.ca](mailto:info@arvoai.ca)
* Check existing [issues](https://github.com/Arvo-AI/aurora/issues) and [documentation](https://arvo-ai.github.io/aurora/docs)

## License

By contributing to Aurora, you agree that your contributions will be licensed under the Apache License 2.0. See [LICENSE](https://github.com/Arvo-AI/aurora/blob/main/LICENSE) for details.

## Thank You!

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Development Setup" icon="code" href="/development/setup">
    Set up your local development environment
  </Card>

  <Card title="Architecture" icon="building" href="/development/architecture-deep-dive">
    Learn about Aurora's architecture
  </Card>

  <Card title="Testing Guide" icon="flask" href="/development/testing">
    Write and run tests for your changes
  </Card>
</CardGroup>