Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
357 lines (265 loc) · 7.8 KB

CONTRIBUTING.md

File metadata and controls

357 lines (265 loc) · 7.8 KB

Contributing to n8n Cloud Deploy

Thank you for considering contributing to n8n Cloud Deploy! This document provides guidelines and instructions for contributing.

Table of Contents

Code of Conduct

This project follows a simple code of conduct:

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help others learn and grow
  • Keep discussions professional

How Can I Contribute?

Reporting Bugs

Before creating a bug report:

  1. Check the existing issues
  2. Review the troubleshooting guide
  3. Ensure you're using the latest version

When creating a bug report, include:

  • Clear, descriptive title
  • Steps to reproduce
  • Expected vs. actual behavior
  • Environment details (OS, gcloud version, etc.)
  • Relevant logs or error messages

Suggesting Enhancements

Enhancement suggestions are welcome! Please:

  • Check if the feature has already been suggested
  • Provide a clear use case
  • Explain why it would be useful to others
  • Consider implementation details if possible

Pull Requests

We actively welcome your pull requests! Here's how:

  1. Fork the repository
  2. Create a feature branch from main
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

Development Setup

Prerequisites

  • Bash 4.0+
  • Google Cloud SDK
  • Access to a GCP project for testing
  • A test domain (optional but recommended)

Local Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/n8n-cloud-deploy.git
cd n8n-cloud-deploy

# Add upstream remote
git remote add upstream https://github.com/llmx-de/n8n-cloud-deploy.git

# Create a branch for your changes
git checkout -b feature/your-feature-name

Testing Changes

Before submitting:

  1. Shellcheck your scripts:
# Install shellcheck
brew install shellcheck  # macOS
sudo apt install shellcheck  # Ubuntu

# Check scripts
shellcheck provision-cloud.sh
shellcheck setup-instance.sh
shellcheck cleanup.sh
shellcheck install.sh
  1. Manual testing:
# Test deployment (use a test project!)
bash provision-cloud.sh

# Test cleanup
bash cleanup.sh

# Test one-liner (if changed install.sh)
curl -fsSL http://localhost:8000/install.sh | bash  # Use local server
  1. Documentation:
  • Update README.md if user-facing changes
  • Update INSTALL.md for installation process changes
  • Update CLAUDE.md for architectural changes

Pull Request Process

Before Submitting

  • Code follows shell scripting best practices
  • All scripts pass shellcheck
  • Changes have been tested manually
  • Documentation has been updated
  • Commit messages are clear and descriptive

Commit Message Format

Use clear, descriptive commit messages:

Add DNS propagation verification to provision script

- Implements auto-retry logic with 10 attempts
- Shows progress to user
- Allows user to continue or cancel
- Fixes #123

Good commit messages:

  • Start with a verb (Add, Fix, Update, Remove, etc.)
  • Keep first line under 50 characters
  • Provide context in the body if needed
  • Reference issues when applicable

Bad commit messages:

  • "fix bug"
  • "changes"
  • "wip"

PR Description Template

## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring

## Testing Done
- [ ] Tested deployment from scratch
- [ ] Tested cleanup functionality
- [ ] Tested with existing resources
- [ ] Shellcheck passed

## Related Issues
Fixes #(issue number)

## Screenshots (if applicable)

Review Process

  1. Maintainers will review your PR
  2. Address any requested changes
  3. Once approved, your PR will be merged
  4. Delete your feature branch after merge

Coding Standards

Shell Script Best Practices

1. Use Bash explicitly:

#!/bin/bash

2. Enable strict mode:

set -e  # Exit on error

3. Quote variables:

# Good
gcloud compute instances create "$INSTANCE_NAME"

# Bad
gcloud compute instances create $INSTANCE_NAME

4. Use meaningful variable names:

# Good
INSTANCE_NAME="n8n-instance"
REGION="us-central1"

# Bad
NAME="n8n-instance"
R="us-central1"

5. Add comments for complex logic:

# Check if static IP already exists to avoid duplicate creation
if gcloud compute addresses describe "$STATIC_IP_NAME" --region="$REGION" &>/dev/null; then
    echo "Static IP already exists. Using existing IP..."
fi

6. Validate user input:

if [ -z "$DOMAIN_NAME" ]; then
    echo "Error: Domain name cannot be empty."
    exit 1
fi

7. Provide helpful error messages:

# Good
echo "❌ Error: gcloud CLI not found!"
echo ""
echo "Please install Google Cloud SDK first:"
echo "  https://cloud.google.com/sdk/docs/install"

# Bad
echo "Error"

8. Use functions for repeated code:

download_file() {
    local file=$1
    local url="$REPO_URL/$file"

    if curl -fsSL "$url" -o "$file" 2>/dev/null; then
        echo "✓ Downloaded: $file"
        return 0
    else
        echo "❌ Failed to download: $file"
        return 1
    fi
}

Documentation Standards

  • Use clear, simple language
  • Provide code examples where helpful
  • Include expected output for commands
  • Add troubleshooting tips for common issues
  • Keep formatting consistent

Testing

Manual Testing Checklist

Before submitting a PR, test these scenarios:

Deployment Testing

  • Fresh deployment with all default options
  • Fresh deployment with custom machine type
  • Fresh deployment with existing static IP
  • Fresh deployment with existing firewall rule
  • Deployment with invalid domain name (should fail gracefully)
  • Deployment with non-propagated DNS (should retry/warn)

Cleanup Testing

  • Delete all resources
  • Delete only instance (keep IP and firewall)
  • Delete with no resources present (should exit gracefully)
  • Cancel cleanup at various stages

Edge Cases

  • No gcloud installed (should error helpfully)
  • Not authenticated to gcloud (should error helpfully)
  • No GCP projects available (should error helpfully)
  • Network timeout during resource creation
  • Ctrl+C during deployment (cleanup state)

Test Environment

Use a dedicated GCP project for testing:

  • Project name: n8n-deploy-testing or similar
  • Keep costs low (use e2-micro for testing)
  • Clean up resources after testing
  • Don't test in production projects!

Areas for Contribution

Looking for ideas? Here are areas that need help:

High Priority

  • Add support for other cloud providers (AWS, Azure, DigitalOcean)
  • Implement automated backup scheduling
  • Add monitoring/alerting setup
  • Create upgrade path for deployed instances

Medium Priority

  • Add support for custom Docker Compose configurations
  • Implement database backend options (PostgreSQL, MySQL)
  • Add support for n8n Queue Mode
  • Create Terraform version of deployment

Documentation

  • Add video tutorial
  • Create architecture diagrams
  • Add more troubleshooting scenarios
  • Translate documentation to other languages

Testing

  • Create automated test suite
  • Add integration tests
  • Implement CI/CD pipeline

Getting Help

License

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

Thank you for contributing! 🙏