Files

GitHub Actions 8294d6ee49 Add QA test outputs, build scripts, and Dockerfile validation

- Created `qa-test-output-after-fix.txt` and `qa-test-output.txt` to log results of certificate page authentication tests.
- Added `build.sh` for deterministic backend builds in CI, utilizing `go list` for efficiency.
- Introduced `codeql_scan.sh` for CodeQL database creation and analysis for Go and JavaScript/TypeScript.
- Implemented `dockerfile_check.sh` to validate Dockerfiles for base image and package manager mismatches.
- Added `sourcery_precommit_wrapper.sh` to facilitate Sourcery CLI usage in pre-commit hooks.

2025-12-11 18:26:24 +00:00

8.1 KiB

Raw Blame History

Contributing to Charon

Thank you for your interest in contributing to CaddyProxyManager+! This document provides guidelines and instructions for contributing to the project.

Code of Conduct
Getting Started
Development Workflow
Coding Standards
Testing Guidelines
Pull Request Process
Issue Guidelines
Documentation

Code of Conduct

This project follows a Code of Conduct that all contributors are expected to adhere to:

Be respectful and inclusive
Welcome newcomers and help them get started
Focus on what's best for the community
Show empathy towards other community members

Getting Started

-### Prerequisites

Go 1.24+ for backend development
Node.js 20+ and npm for frontend development
Git for version control
A GitHub account

Fork and Clone

Fork the repository on GitHub
Clone your fork locally:

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

Add the upstream remote:

git remote add upstream https://github.com/Wikid82/charon.git

Set Up Development Environment

Backend:

cd backend
go mod download
go run ./cmd/seed/main.go  # Seed test data
go run ./cmd/api/main.go   # Start backend

Frontend:

cd frontend
npm install
npm run dev  # Start frontend dev server

Development Workflow

Branching Strategy

main - Production-ready code
development - Main development branch (default)
feature/ - Feature branches (e.g., feature/add-ssl-support)
bugfix/ - Bug fix branches (e.g., bugfix/fix-import-crash)
hotfix/ - Urgent production fixes

Creating a Feature Branch

Always branch from development:

git checkout development
git pull upstream development
git checkout -b feature/your-feature-name

Commit Message Guidelines

Follow the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation only
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

feat(proxy-hosts): add SSL certificate upload

- Implement certificate upload endpoint
- Add UI for certificate management
- Update database schema

Closes #123

fix(import): resolve conflict detection bug

When importing Caddyfiles with multiple domains, conflicts
were not being detected properly.

Fixes #456

Keeping Your Fork Updated

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

Coding Standards

Go Backend

Follow standard Go formatting (gofmt)
Use meaningful variable and function names
Write godoc comments for exported functions
Keep functions small and focused
Handle errors explicitly

Example:

// GetProxyHost retrieves a proxy host by UUID.
// Returns an error if the host is not found.
func GetProxyHost(uuid string) (*models.ProxyHost, error) {
    var host models.ProxyHost
    if err := db.First(&host, "uuid = ?", uuid).Error; err != nil {
        return nil, fmt.Errorf("proxy host not found: %w", err)
    }
    return &host, nil
}

TypeScript Frontend

Use TypeScript for type safety
Follow React best practices and hooks patterns
Use functional components
Destructure props at function signature
Extract reusable logic into custom hooks

Example:

interface ProxyHostFormProps {
  host?: ProxyHost
  onSubmit: (data: ProxyHostData) => Promise<void>
  onCancel: () => void
}

export function ProxyHostForm({ host, onSubmit, onCancel }: ProxyHostFormProps) {
  const [domain, setDomain] = useState(host?.domain ?? '')
  // ... component logic
}

CSS/Styling

Use TailwindCSS utility classes
Follow the dark theme color palette
Keep custom CSS minimal
Use semantic color names from the theme

Testing Guidelines

Backend Tests

Write tests for all new functionality:

func TestGetProxyHost(t *testing.T) {
    // Setup
    db := setupTestDB(t)
    host := createTestHost(db)

    // Execute
    result, err := GetProxyHost(host.UUID)

    // Assert
    assert.NoError(t, err)
    assert.Equal(t, host.Domain, result.Domain)
}

Run tests:

go test ./... -v
go test -cover ./...

Frontend Tests

Write component and hook tests using Vitest and React Testing Library:

describe('ProxyHostForm', () => {
  it('renders create form with empty fields', async () => {
    render(
      <ProxyHostForm onSubmit={vi.fn()} onCancel={vi.fn()} />
    )

    await waitFor(() => {
      expect(screen.getByText('Add Proxy Host')).toBeInTheDocument()
    })
  })
})

Run tests:

npm test              # Watch mode
npm run test:coverage # Coverage report

Test Coverage

Aim for 80%+ code coverage
All new features must include tests
Bug fixes should include regression tests

Pull Request Process

Before Submitting

Ensure tests pass:

# Backend
go test ./...

# Frontend
npm test -- --run

Check code quality:

# Go formatting
go fmt ./...

# Frontend linting
npm run lint

Update documentation if needed
Add tests for new functionality
Rebase on latest development branch

Submitting a Pull Request

Push your branch to your fork:

git push origin feature/your-feature-name

Open a Pull Request on GitHub
Fill out the PR template completely
Link related issues using "Closes #123" or "Fixes #456"
Request review from maintainers

PR Template

## Description
Brief description of changes

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

## Testing
- [ ] Unit tests added/updated
- [ ] Manual testing performed
- [ ] All tests passing

## Screenshots (if applicable)
Add screenshots of UI changes

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review performed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated

Review Process

Maintainers will review within 2-3 business days
Address review feedback promptly
Keep discussions focused and professional
Be open to suggestions and alternative approaches

Issue Guidelines

Reporting Bugs

Use the bug report template and include:

Clear, descriptive title
Steps to reproduce
Expected vs actual behavior
Environment details (OS, browser, Go version, etc.)
Screenshots or error logs
Potential solutions (if known)

Feature Requests

Use the feature request template and include:

Clear description of the feature
Use case and motivation
Potential implementation approach
Mockups or examples (if applicable)

Issue Labels

bug - Something isn't working
enhancement - New feature or request
documentation - Documentation improvements
good first issue - Good for newcomers
help wanted - Extra attention needed
priority: high - Urgent issue
wontfix - Will not be fixed

Documentation

Code Documentation

Add docstrings to all exported functions
Include examples in complex functions
Document return types and error conditions
Keep comments up-to-date with code changes

Project Documentation

When adding features, update:

README.md - User-facing information
docs/api.md - API changes
docs/import-guide.md - Import feature updates
docs/database-schema.md - Schema changes

Recognition

Contributors will be recognized in:

CONTRIBUTORS.md file
Release notes for significant contributions
GitHub contributors page

Questions?

Open a Discussion for general questions
Join our community chat (coming soon)
Tag maintainers in issues for urgent matters

License

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

Thank you for contributing to CaddyProxyManager+! 🎉

8.1 KiB Raw Blame History