Contributing to Techadamia Backend

Guidelines for contributing to the Techadamia Backend project.

Table of Contents#

1. Getting Started
2. Development Workflow
3. Code Standards
4. Commit Messages
5. Pull Requests
6. Code Review
7. Testing Requirements
8. Documentation
9. Reporting Issues

Getting Started#

1. Fork the Repository#

Click "Fork" on GitHub to create your own copy of the repository.

2. Clone Your Fork#

git clone https://github.com/YOUR_USERNAME/Techadamia.git
cd techadamia-backend

3. Add Upstream Remote#

git remote add upstream https://github.com/S3-R4/Techadamia.git

4. Set Up Development Environment#

Follow the Development Guide for the full setup. In brief:

cp .env.example .env          # fill in DATABASE_URL, BOOTSTRAP_TOKEN, etc.
docker compose up -d          # starts postgres (+ redis)
go mod download

Development Workflow#

1. Create Feature Branch#

Branch names should be descriptive and follow convention:

# Features
git checkout -b feature/add-user-roles

# Bug fixes
git checkout -b fix/login-error-handling

# Documentation
git checkout -b docs/update-api-reference

# Performance
git checkout -b perf/optimize-post-queries

# Refactoring
git checkout -b refactor/simplify-service-layer

2. Make Your Changes#

• Write clean, readable code
• Follow code standards (see below)
• Write tests for new functionality
• Update documentation
• Keep commits focused and logical

3. Keep Branch Updated#

# Fetch latest from upstream
git fetch upstream main

# Rebase onto main (if not yet merged)
git rebase upstream/main

# Or merge if rebase conflicts are complex
git merge upstream/main

4. Push Changes#

git push origin feature/add-user-roles

5. Create Pull Request#

1. Go to GitHub
2. Click "Compare & pull request"
3. Fill in title and description
4. Link related issues
5. Wait for review

Code Standards#

Go Code Style#

Formatting#

Use standard Go formatting:

go fmt ./...

Naming Conventions#

// Functions
func CreateUser(ctx context.Context, req *CreateUserRequest) (*User, error)
func (s *Service) Operation() error

// Variables
var (
    maxRetries = 3
    defaultTimeout = 5 * time.Second
)

// Constants
const (
    UserRoleAdmin = "admin"
    DefaultLimit = 20
)

// Private
func privateHelper() {}
var privateVar = ""

// Public (exported)
func PublicFunction() {}
var PublicVar = ""

// Interfaces
type Writer interface {
    Write(p []byte) (n int, err error)
}

Error Handling#

// Always handle errors
if err != nil {
    return fmt.Errorf("operation failed: %w", err)
}

// Use error wrapping
return nil, fmt.Errorf("create user: %w", err)

// Log with context
slog.Error("database operation failed", "user_id", userID, "error", err)

Comments#

Only comment when clarifying non-obvious logic:

// Good: Explains WHY
// bcrypt's DefaultCost balances strong hashing against login latency.
passwordHash, err := bcryptHashPassword(password)

// Bad: Explains WHAT (obvious from code)
// This hashes the password
passwordHash, err := bcryptHashPassword(password)

Interfaces#

// Good: Specific interface for needs
type UserReader interface {
    GetUserByID(ctx context.Context, id uuid.UUID) (*User, error)
}

// Bad: Large interface
type Database interface {
    GetUser() error
    CreateUser() error
    UpdateUser() error
    DeleteUser() error
    // ... 50 more methods
}

Package Organization#

• Use internal/ for private packages
• Keep related functionality together
• Avoid circular dependencies

Testing Standards#

Test File Naming#

main.go         → main_test.go
users.go        → users_test.go
auth.go         → auth_test.go

Test Function Naming#

func TestCreateUser(t *testing.T)
func TestCreateUser_InvalidEmail(t *testing.T)
func TestCreateUser_EmailAlreadyExists(t *testing.T)

Test Structure (Arrange-Act-Assert)#

func TestCreateUser(t *testing.T) {
    // Arrange: Set up test data and mocks
    mockDB := &MockDB{}
    service := &UserService{db: mockDB}
    
    // Act: Perform the operation
    user, err := service.CreateUser(context.Background(), &CreateUserRequest{
        Email: "test@example.com",
    })
    
    // Assert: Verify results
    require.NoError(t, err)
    assert.NotNil(t, user)
    assert.Equal(t, "test@example.com", user.Email)
}

Test Coverage#

• Aim for >80% coverage
• Test error cases
• Test boundary conditions
• Test authorization

go test -cover ./...

Commit Messages#

Follow conventional commit format:

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

<body>

<footer>

Types#

• feat - New feature
• fix - Bug fix
• docs - Documentation
• refactor - Code refactoring
• test - Test additions/modifications
• perf - Performance improvements
• chore - Build, deps, tooling
• ci - CI/CD changes

Scope (Optional)#

feat(auth): add two-factor authentication
fix(posts): handle missing slug in update
docs(api): update endpoint documentation

Subject#

• Use imperative, present tense
• Don't capitalize first letter
• No period at end
• < 50 characters

Body (Optional)#

Explain what and why, not how:

feat(auth): add two-factor authentication

Two-factor authentication improves security by requiring
a second verification method. Users can enable it in
settings and generate backup codes.

Closes #123

Examples#

feat(posts): add category filtering to post listing

fix(auth): handle null session token gracefully

docs: update deployment guide for new environment variables

refactor: extract duplicate validation logic to utils

test: add comprehensive tests for rate limiter

perf: optimize post search with database indexes

Pull Requests#

Before Submitting#

• Code follows style guide (go fmt ./...)
• Tests pass (go test ./...)
• Code is linted (go vet ./...)
• Tests cover new code (>80%)
• Documentation is updated
• No unrelated changes
• Commits are logical and clean
• Branch is updated with main

PR Title#

Use same format as commit messages:

feat(posts): add full-text search support
fix(auth): prevent session hijacking
docs(api): document error codes

PR Description#

Include:

## Description
Brief explanation of changes

## Motivation
Why are these changes needed?

## Changes
- Change 1
- Change 2
- Change 3

## Testing
How to test these changes?

## Checklist
- [x] Code follows style guide
- [x] Tests pass
- [x] Documentation updated
- [ ] Breaking changes documented

## Related Issues
Closes #123

Addressing Feedback#

1. Make requested changes
2. Push to same branch (don't force push unnecessarily)
3. Comment on feedback
4. Request re-review

Code Review#

Review Expectations#

We review for:

• Correctness - Does it work and handle errors?
• Security - Are there security vulnerabilities?
• Performance - Does it impact performance?
• Maintainability - Is it easy to understand?
• Testing - Is it properly tested?
• Documentation - Are changes documented?

Helpful Review Comments#

# Good: Constructive and specific
This could have a race condition. Consider using a mutex here.

# Good: Offers alternative
We might want to use WithContext instead of passing context separately.

# Bad: Vague
This is wrong.

# Bad: Subjective
I don't like this style.

Review as Author#

• Be responsive to feedback
• Ask clarifying questions
• Don't take criticism personally
• Fix issues or discuss concerns

Testing Requirements#

New Code Must Have Tests#

# Feature: Create User
- [ ] Test successful creation
- [ ] Test invalid email validation
- [ ] Test duplicate email handling
- [ ] Test password hashing
- [ ] Test error handling

Run Before Submitting#

# Format code
go fmt ./...

# Check for issues
go vet ./...

# Run all tests (integration; set TEST_DATABASE_URL first)
go test -p 1 ./...

# Run with coverage
go test -p 1 -cover ./...

# Run specific tests
go test -run TestCreateUser ./internal/service

Integration Tests#

Test end-to-end flows:

# Test full registration → login → post creation flow
go test -v -run TestUserWorkflow ./...

Documentation#

Update When#

• Adding new endpoints
• Changing API behavior
• Adding configuration options
• Changing data models
• Adding new features

What to Update#

• README.md - Project overview changes
• API_REFERENCE.md - New/changed endpoints
• ARCHITECTURE.md - Design changes
• CODE_DOCUMENTATION.md - Public API changes
• DEVELOPMENT.md - Development workflow changes
• Code comments - Non-obvious logic

Documentation Format#

Follow existing documentation style:

## Feature Name

Brief description of what the feature does.

### Configuration

Environment variables needed:
- `ENV_VAR` - What it does

### Example

```go
// Code example showing usage
```

### Error Handling

What errors can occur and how they're handled.

Reporting Issues#

Bug Reports#

Include:

## Description
What's the bug?

## Steps to Reproduce
1. Step 1
2. Step 2
3. Bug occurs

## Expected Behavior
What should happen?

## Actual Behavior
What actually happens?

## Environment
- Go version: 1.26.1
- OS: macOS
- PostgreSQL version: 14
- Redis version: 6.2

## Logs
[Include relevant error logs]

Feature Requests#

Include:

## Description
What feature should be added?

## Motivation
Why is this feature needed?

## Proposed Solution
How should it work?

## Alternatives
Are there alternative approaches?

Standards Checklist#

Before Creating PR#

• Created feature branch from main
• Code formatted with go fmt ./...
• Code checked with go vet ./...
• All tests pass: go test ./...
• New code has tests (>80% coverage)
• Commit messages follow convention
• Documentation updated
• No unrelated changes
• Rebased on latest main

Before Requesting Review#

• All checks above pass
• PR description is complete
• Related issues are linked
• No WIP (work in progress) commits

Getting Help#

• Documentation - Read DEVELOPMENT.md and ARCHITECTURE.md
• Code - Review similar implementations in the codebase
• Issues - Check existing GitHub issues
• Discussions - Ask in GitHub Discussions

Recognition#

Contributors will be recognized in:

• CONTRIBUTORS.md (if maintained)
• Release notes
• GitHub contributor page

Thank you for contributing to Techadamia! 🎉

Document Version: 1.0 Last Updated: 2026-05-27 Maintained By: Development Team