Carbon/CONTRIBUTING.md

Contributing to Carbon HTTP Server

Thank you for your interest in contributing to Carbon! This document provides guidelines and instructions for contributing.

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• How to Contribute
• Coding Standards
• Testing
• Pull Request Process
• License

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment. Please:

• Be respectful and considerate in all interactions
• Accept constructive criticism gracefully
• Focus on what is best for the project and community
• Show empathy towards other contributors

Getting Started

Prerequisites

Before contributing, ensure you have:

• Linux operating system (kernel 2.6.27+)
• GCC 4.8+ or Clang 3.4+
• Make build system
• Required dependencies installed

Installing Dependencies

# Debian/Ubuntu/Raspberry Pi OS
make install-deps

# Or manually:
sudo apt-get install -y \
    libssl-dev \
    libmagic-dev \
    libnghttp2-dev \
    build-essential \
    pkg-config \
    zlib1g-dev

Development Setup

1. Fork the repository

   Click the "Fork" button on GitHub to create your own copy.

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/Carbon.git
   cd Carbon
   

3. Add upstream remote

   git remote add upstream https://github.com/Azreyo/Carbon.git
   

4. Build the project

   # Standard build
   make
   
   # Debug build (with symbols, no optimization)
   make debug
   
   # Release build (maximum optimization)
   make release
   

5. Run the server

   ./server
   # Or with a custom config
   ./server server.conf
   

How to Contribute

Reporting Bugs

1. Check existing issues to avoid duplicates
2. Use the bug report template if available
3. Include:
   • Clear description of the issue
   • Steps to reproduce
   • Expected vs actual behavior
   • System information (OS, compiler version)
   • Relevant log output

Suggesting Features

1. Check existing issues and discussions
2. Describe the feature and its use case
3. Explain why it would benefit the project
4. Consider implementation complexity

Submitting Code

1. Create a feature branch

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/bug-description
   

2. Make your changes

   • Follow the coding standards
   • Keep commits focused and atomic
   • Write meaningful commit messages

3. Test your changes

   # Build and test
   make clean && make
   ./server
   
   # Test with Docker
   docker-compose up --build
   

4. Submit a pull request

Coding Standards

C Code Style

• Indentation: 4 spaces (no tabs)
• Brace style: Allman style (braces on new lines)
• Line length: Maximum 100 characters
• Naming conventions:
  • Functions: snake_case
  • Variables: snake_case
  • Constants/Macros: UPPER_SNAKE_CASE
  • Types/Structs: snake_case_t suffix

Example Code Style

// Good example
typedef struct
{
    int socket_fd;
    SSL *ssl;
    bool is_https;
} connection_t;

static int handle_connection(connection_t *conn)
{
    if (!conn)
    {
        return -1;
    }

    // Process connection
    return 0;
}

#define MAX_BUFFER_SIZE 8192

Documentation

• Add comments for complex logic
• Document public functions with purpose and parameters
• Update DOCUMENTATION.md for new features
• Keep README.md current

Security Considerations

When contributing code:

• Validate all input
• Use bounded string operations (snprintf, not sprintf)
• Check return values
• Avoid buffer overflows
• Handle errors gracefully
• Don't log sensitive information

Compiler Warnings

All code must compile without warnings using:

gcc -Wall -Wextra -Werror

Project Structure

Carbon/
├── src/
│   ├── server.c          # Main server implementation
│   ├── config_parser.c   # Configuration file parser
│   ├── server_config.c   # Server configuration defaults
│   ├── server_config.h   # Configuration structures
│   ├── http2.c           # HTTP/2 implementation
│   ├── http2.h           # HTTP/2 headers
│   ├── websocket.c       # WebSocket implementation
│   ├── websocket.h       # WebSocket headers
│   ├── performance.c     # Performance optimizations
│   ├── performance.h     # Performance headers
│   ├── logging.c         # Logging system
│   └── logging.h         # Logging headers
├── www/                  # Static web files
├── server.conf           # Default configuration
├── Makefile              # Build system
├── Dockerfile            # Container build
├── docker-compose.yml    # Container orchestration
├── README.md             # Project overview
├── DOCUMENTATION.md      # Detailed documentation
├── SECURITY.md           # Security policy
├── CONTRIBUTING.md       # This file
└── LICENSE               # License terms

Testing

Manual Testing

# Basic HTTP test
curl http://localhost:8080/

# HTTPS test (if enabled)
curl -k https://localhost:8443/

# WebSocket test
# Open www/websocket-test.html in browser

# HTTP/2 test
curl --http2 -k https://localhost:8443/

Docker Testing

# Build and run
docker-compose up --build

# Check logs
docker logs carbon-http-server

# Health check
curl http://localhost:8080/

Performance Testing

# Using Apache Benchmark
ab -n 10000 -c 100 http://localhost:8080/

# Using wrk
wrk -t4 -c100 -d30s http://localhost:8080/

Pull Request Process

1. Ensure your code:

   • Compiles without warnings
   • Follows coding standards
   • Is properly documented
   • Doesn't break existing functionality

2. Update documentation if needed:

   • README.md for user-facing changes
   • DOCUMENTATION.md for technical details
   • Code comments for complex logic

3. Create the pull request:

   • Use a clear, descriptive title
   • Reference any related issues
   • Describe what changes were made and why
   • Include testing steps

4. Review process:

   • Maintainers will review your PR
   • Address any requested changes
   • Be patient and responsive

PR Title Format

feat: Add new feature description
fix: Fix bug description
docs: Update documentation
refactor: Code refactoring
perf: Performance improvement
security: Security fix

Areas for Contribution

Current areas where contributions are welcome:

• Unit test implementation
• Additional HTTP/2 features
• Performance optimizations
• Documentation improvements
• Bug fixes
• Security enhancements
• Cross-platform support research
• CI/CD pipeline improvements

Questions?

If you have questions about contributing:

1. Check existing documentation
2. Search closed issues
3. Open a discussion or issue

License

By contributing to Carbon, you agree that your contributions will be licensed under the same MIT License (Modified - Non-Commercial) that covers the project.

Important: Commercial use of contributions requires explicit permission from the copyright holders. See the LICENSE file for full terms.

---

Thank you for contributing to Carbon HTTP Server! 🔥