Contribution Guidelines and Principles¶

This document outlines the coding conventions and guidelines for contributing Go code to this project. We strictly follow standard Go community practices.

General Principles¶

Consistency: Adhere to the style of existing code.
Simplicity: Go favors simplicity and readability. Avoid clever tricks.
Idiomatic Go: Follow the guidelines in Effective Go.

Local Development and Dependencies¶

It is paramount to use as few dependencies as possible. Dependencies must be checked for update-frequency and up-to-dateness.

See the Local Development guide for setting up your development environment.

Naming Conventions¶

We follow the naming conventions described in Effective Go: Names and Go Code Review Comments.

Packages: Use short, concise, lowercase single-word names (e.g., user, http). Avoid underscores or mixedCaps.
Variables/Constants: Use MixedCaps or mixedCaps. Acronyms should be consistent (e.g., ServeHTTP, not ServeHttp).
Interfaces: One-method interfaces are named by the method name plus an -er suffix or similar modification to construct an agent noun (e.g., Reader, Writer).
Getters: Do not use the Get prefix for getters. Use Owner() instead of GetOwner().

Code Style¶

Error Handling¶

Errors in Go should be handled explicitly. Do not ignore errors using _ unless you have a very good reason and document it.

// Bad
func process() {
    result, _ := dangerousOp()
}

// Good
func process() error {
    result, err := dangerousOp()
    if err != nil {
        // Wrap errors with context
        return fmt.Errorf("failed to process operation: %w", err)
    }
    return nil
}

Comments & Documentation¶

Godoc: All exported (capitalized) functions, types, and variables must have documentation comments.
Format: Comments should start with the name of the thing being described and end with a period.

// User represents a registered user in the system.
type User struct {
    ID   string
    Name string
}

// Save persists the user to the database.
// It returns an error if the database connection fails.
func (u *User) Save() error {
    // ...
}

Imports¶

Group imports into standard library, third-party, and internal packages, separated by a blank line.

import (
    "fmt"
    "os"

    "github.com/gin-gonic/gin"

    "gitlab.opencode.de/bwi/orca/cloudapi/pkg/utils"
)

Pull Requests¶

Scope: Keep PRs small and focused.
Tests: Include unit tests for new functionality (using _test.go files).
Build: Ensure go build ./... and go test ./... pass.
Templates: Use the provided template and try to fill it out completely.

The CI-Pipeline will measure Test-Coverage; Pull Requests without enough coverage might be rejected

Commit Messages¶

Follow the Conventional Commits specification.

feat: add user registration handler
fix: handle nil pointer in auth middleware
refactor: simplify error checking logic