akiyama-manga/CONTRIBUTING.md

Contributing Guidelines

Development Setup

1. Fork the repository
2. Clone locally:

git clone https://github.com/yourusername/akiyama-manga.git
cd akiyama-manga

3. Create a feature branch:

git checkout -b feature/your-feature

Code Style

Go Code

• Follow Go Code Review Comments
• Run go fmt ./... before committing
• Use golangci-lint for linting

make fmt
make lint

Naming Conventions

• Functions: camelCase
• Constants: UPPER_SNAKE_CASE
• Variables: camelCase
• Structs: PascalCase

Comments

• Export comments should start with the name
• Unexported functions should be documented
• Complex logic should have inline comments

// GetMangaByID retrieves a manga by its UUID
func (s *MangaService) GetMangaByID(id uuid.UUID) (*models.Manga, error) {
    // Implementation
}

Frontend Code

HTML/CSS

• Use semantic HTML
• Follow CSS naming conventions (kebab-case)
• Mobile-first responsive design

JavaScript

• Use vanilla JavaScript (no jQuery)
• Use const by default, let when necessary
• Use template literals for strings

Testing

Write tests for all new features:

go test -v ./...
go test -v -coverprofile=coverage.out ./...

Commit Messages

Follow conventional commits:

feat: add search functionality
fix: correct manga rating calculation
docs: update API documentation
refactor: simplify user service
test: add upload tests

Pull Request Process

1. Update documentation
2. Add/update tests
3. Run linter and tests locally
4. Create descriptive PR title and description
5. Link related issues

Architecture Guidelines

Backend

• Models - Data structures with GORM tags
• Services - Business logic
• Handlers - HTTP request/response handling
• Middleware - Cross-cutting concerns
• Storage - External storage (S3)

Frontend

• Templates - Server-rendered HTML
• Static - CSS and JavaScript assets
• Responsive - Mobile-first design

Database Migrations

For schema changes:

1. Modify model in internal/models/models.go
2. Application will auto-migrate on startup
3. Document breaking changes

Adding Features

New Endpoint

1. Create handler in internal/handlers/
2. Add route in cmd/server/main.go
3. Create service method if needed
4. Add tests
5. Document in API.md

New Database Table

1. Create model in internal/models/models.go
2. Add to migration in internal/database/db.go
3. Create service if needed
4. Add handlers

Documentation

Update docs for:

• New features
• API changes
• Configuration options
• Deployment procedures

Performance Considerations

• Use database indexes for frequently queried fields
• Implement pagination for large datasets
• Cache frequently accessed data
• Minimize S3 API calls

Security

• Never commit credentials
• Validate all user input
• Use parameterized queries
• Implement rate limiting
• Use HTTPS in production

Release Process

1. Update version numbers
2. Update CHANGELOG
3. Create release tag
4. Build release artifacts
5. Create GitHub release

Questions?

• Check existing issues and discussions
• Review documentation
• Ask in pull requests or issues