tor-guard-relay/CONTRIBUTING.md

Contributing to Tor Guard Relay 🧅

First off, thank you for considering contributing to this project! Every contribution helps make the Tor network stronger and more accessible.

🌟 Ways to Contribute

1. Running a Relay

The best contribution is running your own Tor relay using this project! Share your experience and help others.

2. Reporting Issues

• 🐛 Found a bug? Open an issue
• 💡 Have a feature idea? Share it!
• 📖 Documentation unclear? Let us know!

3. Improving Documentation

• Fix typos or unclear explanations
• Add examples or use cases
• Translate documentation
• Create tutorials or guides

4. Code Contributions

• Bug fixes
• New features
• Performance improvements
• Test coverage

---

🚀 Getting Started

Prerequisites

• Docker installed
• Git basics
• Understanding of Tor relay operation (optional but helpful)

Fork & Clone

# Fork the repo on GitHub, then:
git clone https://github.com/YOUR_USERNAME/tor-guard-relay.git
cd tor-guard-relay

# Add upstream remote
git remote add upstream https://github.com/r3bo0tbx1/tor-guard-relay.git

Local Development

# Build locally
docker build \
  --build-arg BUILD_DATE="$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \
  --build-arg BUILD_VERSION="dev" \
  -t onion-relay:dev \
  -f Dockerfile .

# Test your changes
docker run --rm onion-relay:dev cat /build-info.txt

# Test with configuration
docker run -d \
  --name test-relay \
  --network host \
  -v ./examples/relay.conf.example:/etc/tor/torrc:ro \
  onion-relay:dev

---

📝 Contribution Guidelines

Branch Naming

• feature/your-feature-name - New features
• fix/bug-description - Bug fixes
• docs/what-you-changed - Documentation
• chore/maintenance-task - Maintenance

Commit Messages

Follow Conventional Commits:

feat: add ARM64 support for Raspberry Pi
fix: correct permission handling in entrypoint
docs: update deployment guide for Cosmos
chore: bump Alpine to edge

Format:

<type>: <description>

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Code style (formatting, no logic change)
• refactor: Code refactoring
• perf: Performance improvement
• test: Adding tests
• chore: Maintenance tasks
• ci: CI/CD changes

Pull Request Process

1. Create a branch from main

   git checkout -b feature/my-feature
   

2. Make your changes

   • Keep commits atomic and focused
   • Test thoroughly
   • Update documentation if needed

3. Push to your fork

   git push origin feature/my-feature
   

4. Open a Pull Request

   • Use a clear title
   • Describe what changed and why
   • Reference any related issues
   • Add screenshots if UI-related

5. Respond to feedback

   • Be open to suggestions
   • Make requested changes
   • Keep discussion professional

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Other (specify)

## Testing
How did you test this?

## Checklist
- [ ] Code follows project style
- [ ] Documentation updated
- [ ] Tested locally
- [ ] No breaking changes (or documented)

---

🧪 Testing Guidelines

Docker Build Testing

# Test build
docker build -f Dockerfile -t test:latest .

# Verify scripts are executable
docker run --rm test:latest ls -la /usr/local/bin/

# Test diagnostics
docker run --rm test:latest status || echo "Expected to fail without config"

Configuration Validation

# Test with example config
docker run --rm \
  -v ./examples/relay.conf.example:/etc/tor/torrc:ro \
  test:latest tor --verify-config -f /etc/tor/torrc

Multi-Architecture Testing

# Build for specific platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -f Dockerfile \
  -t test:multiarch .

---

📖 Documentation Standards

Markdown Style

• Use headers hierarchically (h1 → h2 → h3)
• Include code blocks with language tags
• Add emoji sparingly for visual hierarchy
• Keep line length reasonable (~80-100 chars)
• Use tables for structured data

Code Comments

#!/bin/bash
# Brief description of script purpose

# Function: what_it_does
# Parameters: $1 - description
# Returns: description
function_name() {
  # Inline comments for complex logic
  command
}

Example Quality

• Provide working, copy-paste-ready examples
• Include expected output
• Explain parameters
• Note prerequisites

---

🔒 Security Guidelines

Reporting Security Issues

DO NOT open public issues for security vulnerabilities.

Instead:

1. Email: r3bo0tbx1@brokenbotnet.com
2. Include:
   • Description of vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

Security Best Practices

• Never commit secrets or credentials
• Use read-only mounts for configs
• Maintain non-root user operation
• Document security implications of changes
• Test permission handling

---

🎨 Code Style

Dockerfile

# Group related RUN commands
RUN apk add --no-cache \
    package1 \
    package2 && \
    cleanup_command

# Use specific versions for reproducibility
FROM alpine:edge

# Document ARGs
ARG BUILD_DATE
ARG BUILD_VERSION="1.4"

Bash Scripts

#!/bin/bash
set -euo pipefail  # Always use strict mode

# Use meaningful variable names
readonly CONTAINER_NAME="guard-relay"

# Check prerequisites
if ! command -v docker &> /dev/null; then
    echo "Error: Docker not found"
    exit 1
fi

YAML

# Use 2-space indentation
# Quote strings when ambiguous
# Comment complex sections

services:
  relay:
    # Service configuration
    image: "r3bo0tbx1/onion-relay:latest" # or ghcr.io/r3bo0tbx1/onion-relay:latest

---

🏷️ Issue Labels

When creating issues, use appropriate labels:

Label	Purpose
bug	Something isn't working
enhancement	New feature or request
documentation	Improvements or additions to docs
good first issue	Good for newcomers
help wanted	Extra attention is needed
question	Further information is requested
security	Security-related issue

---

🤝 Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for everyone.

Expected Behavior

• ✅ Be respectful and considerate
• ✅ Accept constructive criticism gracefully
• ✅ Focus on what's best for the community
• ✅ Show empathy toward others

Unacceptable Behavior

• ❌ Harassment or discrimination
• ❌ Trolling or insulting comments
• ❌ Public or private harassment
• ❌ Publishing others' private information

Enforcement

Violations may result in:

1. Warning
2. Temporary ban
3. Permanent ban

Report issues to: r3bo0tbx1@brokenbotnet.com

---

📞 Getting Help

• 💬 GitHub Discussions
• 🐛 Issue Tracker
• 📧 Email: r3bo0tbx1@brokenbotnet.com
• 🌐 Tor Project Forum

---

🎉 Recognition

Contributors will be:

• Listed in release notes
• Mentioned in CHANGELOG
• Added to README acknowledgments (for significant contributions)

---

📜 License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

🙏 Thank You!

Every contribution, no matter how small, makes a difference. Thank you for helping make the Tor network stronger and more accessible!

Happy Contributing! 🧅✨