Contributing Guide

Thank you for considering contributing to go-clean-arch! We welcome any contributions that help improve this project. This guide will provide you with the necessary information to set up your development environment and follow the project's standards.

Development Environment

The development setup is the same as the main project setup. Please follow the Installation Guide to get the application and database running on your local machine.

The key command for development is:

make up

This command uses docker-compose to run the required MySQL database and air for live-reloading of the Go application. When you save a .go file, air will automatically recompile and restart the server, speeding up your development workflow.

The configuration for air can be found in .air.toml.

Installing Development Tools

The project relies on several command-line tools for linting, testing, and mock generation. The Makefile can install these for you locally inside a bin/ directory.

make install-deps
This will install air, golangci-lint, mockery, and other tools.

Running Tests

We use gotestsum for running tests and generating reports. The Makefile provides convenient targets for testing.

To run all tests in short mode (skipping long-running tests): 

make tests

This command runs tests with the -race flag to detect race conditions and generates a coverage.out file for code coverage analysis.

To run all tests and get a detailed parsed output in the console: 

make tests-complete

Linting

We use golangci-lint to enforce code style and catch common errors. The linter is configured via the .golangci.yaml file in the project root.

To run the linter on the entire codebase, use the following command:

make lint

Please ensure your code passes the linting checks before submitting a pull request.

Generating Mocks

This project uses mockery to generate mocks for testing. Interfaces that need to be mocked are marked with a //go:generate directive.

For example, in article/service.go:

// ArticleRepository represent the article's repository contract
//go:generate mockery --name ArticleRepository
type ArticleRepository interface {
    // ... methods
}

To regenerate all mocks in the project, run the go generate command recursively:

go generate ./...

Alternatively, you can use the make target:

make go-generate

Commit the generated mock files along with your changes.

Submitting a Pull Request

  1. Fork the repository.
  2. Create a new branch for your feature or bug fix (git checkout -b feature/my-new-feature).
  3. Make your changes.
  4. Ensure your code is formatted (gofmt), passes the linter (make lint), and all tests pass (make tests).
  5. Commit your changes with a clear and descriptive commit message.
  6. Push your branch to your fork (git push origin feature/my-new-feature).
  7. Open a pull request against the main branch of the bxcodec/go-clean-arch repository.