Contributing

We welcome contributions to the GoApp project! This guide provides all the information you need to get your development environment set up, run tests, and understand our coding standards.

Development Setup

To start developing, you'll need to set up the project locally. The recommended approach is to use Docker Compose, as it handles both the application and the database.

  1. Follow the Quick Start guide to get the application running with Docker Compose.
  2. The source code is mounted as a volume, so any changes you make to the code on your local machine will be immediately reflected in the running container. You may need to restart the goapp container to see your changes take effect if you're using go run.

Running Tests

The project includes a suite of unit tests to ensure the core business logic is working correctly. Tests are located in _test.go files alongside the code they are testing (e.g., users_test.go for users.go).

To run all tests and generate a coverage report, use the following command from the project root. This is the same command used in our CI pipeline.

go test -coverprofile=coverage.txt -covermode=atomic $(go list ./... | grep -v /cmd)

Let's break down this command:

  • go test ./...: Runs tests for all packages in the current directory and its subdirectories.
  • -coverprofile=coverage.txt: Generates a coverage report and saves it to coverage.txt.
  • -covermode=atomic: Specifies the mode for coverage analysis. atomic is required for packages that may be run in parallel.
  • $(go list ./... | grep -v /cmd): This part is a filter. It lists all packages but excludes those inside the /cmd directory, as the main packages are typically not unit-tested directly.

Viewing Coverage

After running the tests, you can view the coverage report in your browser:

go tool cover -html=coverage.txt

Continuous Integration (CI)

We use GitHub Actions to automate our build and test processes. The workflows are defined in the .github/workflows/ directory.

1. Build and Test (go.yml)

This workflow runs on every push and pull request to the master branch. It performs two main jobs:

  • Build: It checks out the code, sets up Go, and runs go build -v ./... to ensure the application compiles successfully.
  • Test: It runs the unit test command described above to verify that all tests pass.

2. Static Analysis (golangci-lint.yml)

This workflow also runs on every push and pull request. It uses golangci-lint, a popular Go linter aggregator, to perform static analysis on the code.

This helps enforce code quality, find potential bugs, and maintain a consistent style across the codebase. Any new code should pass the linter before being merged.

Code Style and Principles

While we don't have a strict written style guide, the project follows standard Go conventions and the principles of Clean Architecture.

  • Clarity and Simplicity: Write code that is easy to read and understand.
  • Separation of Concerns: Keep business logic separate from infrastructure code.
  • Testability: Write code that is easily unit-testable. Use interfaces to mock dependencies.
  • Error Handling: Handle errors explicitly. Use the naughtygopher/errors package to wrap errors with context.

When contributing, please ensure your code adheres to these principles and that you add relevant tests for any new functionality.