Contributing¶

Guidelines for contributing to DB Provision Operator.

Getting Started¶

Prerequisites¶

Go 1.21+
Docker
kubectl
kind or minikube
Make

Setup¶

# Fork and clone
git clone https://github.com/YOUR_USERNAME/db-provision-operator.git
cd db-provision-operator

# Add upstream remote
git remote add upstream https://github.com/panteparak/db-provision-operator.git

# Install tools
make install-tools

# Verify setup
make test

Development Workflow¶

1. Create Branch¶

# Update main
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/my-feature

2. Make Changes¶

Follow these guidelines:

Code style: Follow Go conventions
Comments: Document exported functions
Tests: Add tests for new code
Commits: Use conventional commits

3. Test Changes¶

# Run all tests
make test

# Run linters
make lint

# Run E2E tests (requires cluster)
make test-e2e

4. Submit PR¶

# Push branch
git push origin feature/my-feature

Open PR against main branch.

Code Style¶

Go Guidelines¶

Follow Effective Go
Run gofmt and goimports
Use meaningful variable names
Keep functions focused and small

Naming Conventions¶

Type	Convention	Example
Files	`snake_case.go`	`database_controller.go`
Packages	`lowercase`	`database`
Types	`PascalCase`	`DatabaseInstance`
Functions	`PascalCase` (exported)	`CreateDatabase`
Variables	`camelCase`	`dbInstance`
Constants	`PascalCase` or `UPPER_SNAKE`	`DefaultPort`

Error Handling¶

// Good
if err != nil {
    return fmt.Errorf("failed to create database: %w", err)
}

// Bad
if err != nil {
    return err  // No context
}

Logging¶

// Use structured logging
log.Info("Reconciling database",
    "namespace", db.Namespace,
    "name", db.Name)

// Error logging
log.Error(err, "Failed to create database",
    "namespace", db.Namespace,
    "name", db.Name)

Commit Messages¶

Use Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types¶

Type	Description
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation
`style`	Formatting (no code change)
`refactor`	Code refactoring
`test`	Tests
`chore`	Maintenance

Examples¶

feat(database): add support for PostgreSQL extensions

fix(user): handle special characters in password generation

docs: update installation guide

test(e2e): add backup/restore tests

Pull Requests¶

PR Title¶

Follow conventional commit format:

feat(database): add support for schemas

PR Description¶

Use the template:

## Description
Brief description of changes.

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

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

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests pass

Review Process¶

Automated checks must pass
At least one maintainer approval
All conversations resolved
Squash and merge

Adding New Features¶

Adding a New CRD¶

Define API in api/v1alpha1/:

kubebuilder create api --group dbops --version v1alpha1 --kind NewResource

Implement types in *_types.go
Generate manifests:
```
make generate
make manifests
```
Implement controller in internal/controller/
Add tests
Update documentation

Adding Database Engine Support¶

Implement DatabaseEngine interface in internal/database/
Add engine-specific options to API types
Register engine in factory
Add tests for new engine
Add documentation

Testing Guidelines¶

Unit Tests¶

func TestCreateDatabase(t *testing.T) {
    // Setup
    db := &Database{...}

    // Execute
    err := createDatabase(db)

    // Assert
    assert.NoError(t, err)
}

Integration Tests¶

var _ = Describe("Database Controller", func() {
    Context("When creating Database", func() {
        It("Should create database in instance", func() {
            // Test code
        })
    })
})

E2E Tests¶

var _ = Describe("Database E2E", func() {
    It("Should create and delete database", func() {
        // Create instance
        // Create database
        // Verify database exists
        // Delete database
        // Verify database removed
    })
})

Documentation¶

Code Documentation¶

// CreateDatabase creates a new database in the instance.
// It returns an error if the database already exists or
// if the connection to the instance fails.
func CreateDatabase(ctx context.Context, db *Database) error {
    // ...
}

User Documentation¶

Update docs in docs/ directory when: - Adding new features - Changing API - Adding new CRDs - Changing behavior

Release Process¶

Releases are automated via GitHub Actions:

Create tag: git tag v1.2.3
Push tag: git push origin v1.2.3
GitHub Actions builds and releases

Getting Help¶

Questions: Open a GitHub Discussion
Bugs: Open a GitHub Issue
Security: Email security@example.com

Code of Conduct¶

Be respectful and inclusive. See CODE_OF_CONDUCT.md.