🤝 GoFr Contribution Guidelines

Welcome! 🎉 We're excited to have you contribute to GoFr, a robust framework designed for building scalable microservices with Kubernetes-native support and built-in observability.

Whether you're fixing a typo or contributing a major feature, please follow the guidelines below to ensure smooth collaboration and code quality across the project.

✨ Making Contributions

✅ Small Changes (Quick Edits)
For minor updates—such as typo corrections, variable renaming, or improving error messages—you can directly edit the file on GitHub. GitHub will automatically create a temporary branch and open a pull request (PR). This is ideal for:

Spelling or grammar fixes

Renaming variables or functions for clarity

Small documentation edits

📦 Larger Changes (Recommended Process)

For substantial updates (new features, refactoring, etc.), follow these steps:

Discuss Before You Build (optional)
Want feedback before diving in? Use the GitHub Discussions to share your ideas.

Editor Setup
Ensure your editor is configured to auto-run goimports and golangci-lint on file changes. Non-compliant code will fail CI checks.

Issue Assignment
Only start working on an issue once it's assigned to you. To get assigned, comment on the issue requesting assignment from a maintainer.

Triage-Labeled Issues
These require discussion before starting. Please contact maintainers on the GitHub thread before proceeding.

Language Convention
Use American English throughout the project (e.g., favor instead of favour).

Tests Required
Every code change must be covered with relevant test cases. No PR should reduce code coverage.

Raise PRs to development branch
All PRs must be submitted to the development branch from your feature branch. Only open a PR when the feature is complete and ready for review.

Code Reviews
All PRs require approval from at least 2 GoFr developers. Be prepared to clarify your changes if needed.

🧪 GoFr Testing Policy

Quality and reliability are at the heart of GoFr. Please adhere to these testing guidelines:

🔬 Test Types

*Unit Tests: Required for every new function or method.

*Integration Tests: Mandatory for major feature additions.

📈 Test Coverage

*No PR should reduce test coverage.

*Coverage is enforced using Code Climate or other tools integrated into the pipeline.

🧪 Test Writing Style

*Use Go’s standard testing package.

*Use clear, descriptive names for test functions.

go
Copy
Edit
func TestFunctionName(t *testing.T) {
    // Test logic
}
Prefer table-driven tests for multiple input/output scenarios.

🐳 Docker Setup for Local Testing

Some services are required to pass the test suite. Use Docker to spin up dependencies:

bash
Copy
Edit
# MongoDB
docker run --name mongodb -d -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=user \
  -e MONGO_INITDB_ROOT_PASSWORD=password \
  mongodb/mongodb-community-server:latest

# Redis
docker run --name gofr-redis -p 2002:6379 -d redis:7.0.5

# MySQL
docker run --name gofr-mysql -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=test -p 2001:3306 -d mysql:8.0.30

# PostgreSQL
docker run --name gofr-pgsql -d -e POSTGRES_DB=customers \
  -e POSTGRES_PASSWORD=root123 -p 2006:5432 postgres:15.1

# Kafka, Zipkin, Cassandra, Solr, LocalStack, SurrealDB, etc.
# (Full list in docs/docker-services.md or below)

Note: Default ports in Docker are offset to avoid conflicts with local installations. If you change them, update your .local.env file accordingly.

🔒 Coding Best Practices

*No Global Variables: Always inject dependencies (e.g., DB, Logger).

*No init(): Avoid using package-level init functions.

*Documentation: Every exported function must have a valid GoDoc comment.

*No Secrets in Code: Use environment variables for usernames, passwords, and keys.

*Lean Interfaces: Accept only what’s needed. The consuming package defines interfaces.

*Avoid Type Assertion Pitfalls: Prefer concrete types over asserting interfaces.

*Use context.Context: Always as the first parameter. Use typed keys to avoid conflicts.

📦 External Libraries

Favor simplicity: A little copying is better than a little dependency.

All third-party libraries should be carefully evaluated and wrapped in interfaces for future replacement/testing flexibility.

🔖 Versioning

GoFr follows Semantic Versioning. Changes should be documented and appropriately versioned.

📚 Documentation Contributions

After changing or adding code:

Update the relevant files in development/docs.

For new docs:

*Create a new .md file.

*Reference it in navigation.js.

*Add/update code samples as needed.

*Place new images in docs/public/.

*Use correct Markdown syntax and formatting standards.

*Docs are published to gofr.dev after pushing to the /docs directory on the development branch.

🏁 Thank You!

Your contributions are what make GoFr better every day. We appreciate your time, effort, and attention to detail.

Let’s build something awesome together. 💙