DEVELOPMENT.adoc

Git Provider Sync: Developer Guide

Table of Contents

• Introduction
• Prerequisites
  • Development Environment
  • Additional Tools
  • Installing Developer Tools
• Development Workflow
  • Make Targets
  • Running Tests
• Code Quality Assurance
  • Local Quality Checks
  • Quality Check Tools
  • Interpreting Quality Check Results

Introduction

This guide covers everything from prerequisites to development workflows and quality assurance processes.

Prerequisites

Development Environment

Dependency	Minimum Version
Go	1.23+
Podman	4.9.3+
Git	2.43+
Make (GNU)	4.3+
Ubuntu	24.04

Additional Tools

Tool	Description	Installation
golangci-lint	Umbrella project for various Go linters	go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
mockery	Mock code generator for Go	go install github.com/vektra/mockery/v2@latest
GoReleaser	Build and release artifacts for Go	go install github.com/goreleaser/goreleaser@latest
syft	CLI tool for generating SBOM	curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s — -b /usr/local/bin
wsl	Formatter tool	go install github.com/bombsimon/wsl/v3/cmd/wsl@master
cosign	Signing artifacts and images	go install github.com/sigstore/cosign/cmd/cosign@latest
staticcheck	Static linting tool	go install honnef.co/go/tools/cmd/staticcheck@latest
govulncheck	Vulnerability tool	go install golang.org/x/vuln/cmd/govulncheck@latest
OpenSSF Scorecard	Security health for open-source projects	go install github.com/ossf/scorecard/v4/cmd/scorecard@latest

Installing Developer Tools

You have two options for installing the additional developer tools:

Option 1: Run the helper install script

./scripts/installdevprereq.sh

Option 2: Use the Make target

make install/prereq

Development Workflow

Make Targets

We use Make to automate various development tasks. To see all available targets:

make help

ℹ️	Make targets are hierarchical. For example, make quality runs all quality checks, while make quality/license only runs the license check. For detailed information on each target, refer to the Makefile.

Running Tests

Our tests are written in Go’s idiomatic table-driven style.

Run all tests

make test

Run tests with coverage

make test/cover

Code Quality Assurance

Local Quality Checks

Before submitting a Pull Request, it’s crucial to run the quality checks locally:

make quality

💡	If a check fails, you can run individual checks (e.g., make quality/lint) to pinpoint and address specific issues.

Quality Check Tools

Linting

• MegaLinter: A comprehensive suite of linting tools

  • Covers BASH, Markdown, YAML, GitHub Actions, and security scans

• golangci-lint: Go-specific linters

  • Configuration: .golangci.yml

License Compliance

• REUSE: Ensures proper licensing and copyright notices

Commit Structure

• Conform: Checks commit message format

Go-specific Checks

• Standard Go tests

• Additional tools: go vet, staticcheck, go mod tidy, govulncheck

Interpreting Quality Check Results

If any checks fail, follow these steps:

1. Run individual checks to isolate the issue (e.g., make quality/lint)

2. Carefully review the error messages in your terminal output

3. Consult the documentation for the specific tool that reported the error

4. Address the issues and re-run the checks

5. For CI pipeline failures, reproduce the issue locally, fix it, and update your Pull Request