gogolcorp / go-yave

🥭 | A Golang repository template with conventions, guidelines, project folder structure, Dockerization, CI/CD, labeler, releaser, automation [...] and some more, to start a new Go project in SECONDS.

How to use this repo as a template for your project

I - Introduction

The purpose of this repository is to provide a solid, complete and adaptable base of a Golang-oriented product in a project-managed repository, in order to start a new project with a maximum time saving.

This repository provides commit writting and branch naming conventions, issues and pull request templates, and a custom issues labels preset.

But also CI/CD and release using GitHub Actions, GitHub Container Registry and Docker.

And finally, a simple RESTful API, using Golang, Postgres and Adminer, build with Docker and Docker Compose, using a Makefile.

This repository gathers all the good practices that I have learned over time, both in terms of organization and good maintenance of a project over time as well as in terms of automation, availability and consistancy.

II - Table of content

• I - Introduction
• II - Table of content
• III - Folder structure
• IV - Conventions, templates and labels
  • A - Commit conventions
  • B - Branch naming convention
  • C - Issue template
  • D - Pull request template
  • E - Custom issues labels preset
• V - CI/CD, release and container registry
  • A - CI
  • B - CD
  • C - Release
  • D - Labeler
• VI - Project setup
  • A - Stack
  • B - Makefile
• VII - Contributing
• VIII - License

III - Folder structure

The structure of this project follows these conventions.

• /.github: Conventions, template, labels, ci, cd, settings
• /cmd: main files
• /build: Dockerfiles
• /config: Environment files
• /deploy: Docker Compose files
• /internal: "private" code
• /pkg: "public" code
• /scripts: Makefile bash scripts for setup/install/start

IV - Conventions, templates and labels

A - Commit conventions

tag(scope): #issue_id - message

See COMMIT_CONVENTIONS.md for more informations.

B - Branch naming convention

type_scope-of-the-work

See BRANCH_NAMING_CONVENTIONS.md for more informations.

C - Issue template

See user-story.md for more informations.

D - Pull request template

See pull_request_template.md for more informations.

E - Custom issues labels preset

The labels preset is located at .github/settings.yml.

You can add, edit or remove them. To automatically update these labels, you need to install the "Settings" GitHub app, which will syncs repository settings defined in the file above to your repository.

V - CI/CD, release and container registry

A - CI

The CI workflow is located at .github/workflows/ci.go.yml. It's triggered a each push on all branches.

It consist of:

• install Golang on the VM
• get the dependancies using the cache of other Actions run
• lint the files to check or syntax errors
• build the application

B - CD

The CD workflow is located at .github/workflows/cd.docker.yml. It's triggered a each push on main branch.

It consist of:

• login into the GitHub container registry (ghcr.io)
• build and push the Golang api using the production Dockerfile located at build/pakage/sample-api/Dockerfile

After that, you can check the pushed container at: https://github.com/<username>?tab=packages&repo_name=<repository-name>

IMPORTANT: you need to update the production Dockerfile with your username AND repository name. Otherwise, there will be errors at push:

LABEL org.opencontainers.image.source = "https://github.com/<username>/<repository-name>"

C - Release

The release workflow is located at .github/workflows/md.release.yml. It's triggered manually by user input at: Actions > RELEASE.

IMPORTANT: you need to set the image tag in the action input, for the action to be able to push the docker image and create a release with a specific version. The image tag is a SemVer tag, e.g. 1.0.2.

It consist of:

• check if the environment match the branch
• do the CD (docker) action again, but with a specific image tag
• create a release with the same tag, filled with the generated changelog as closed issues since the last release

After that, you can check the release at https://github.com/<username>/<repository-name>/releases.

D - Labeler

The labeler workflow consists in assigning specific labels on pull requests according to the files that have been modified in the commits attached to this pull request.

VI - Project setup

The project use Docker and Docker Compose to build and run local and distant images in our workspace.

A - Stack

All the images use the same network, more informations at docker-compose.yml

CONTAINER	PORT	IMAGE
GOLANG	3333:3333	build/pakage/sample-api/Dockerfile
ADMINER	3334:8080	build/package/adminer/Dockerfile
POSTGRES	5432:5432	postgres:latest

Adminer is a GUI that allows us to manage your database by permetting to to create, edit, delete the different entities, tables, etc.

B - Makefile

TL;DR

make setup-env start logs

make help

Display informations about other commands.

make setup-env

Copy the sample environment files.

make start

Up the containers with full cache reset to avoid cache errors.

make stop

Down the containers.

make logs

Display and follow the logs.

make lint

Lint the Go files using gofmt.

VII - Contributing

See CONTRIBUTING.md for more informations.

VIII - License

Under MIT license.

go-yave's Issues

As a repository owner, I want to have commits/branches/issues/pull request conventions

Tasks:

• Commit conventions
• Branches conventions
• Issues conventions
• Pull requests conventions

[US] As a developer, I want to have a short go prohject with many features as a default project

Tasks:

• task 1
• task 2
• task 3

[US] As a developer, I want to have one Dockerfile for both dev + prod env

Tasks:

• merge dockerfile
• set target to docker compose
• set target to actions

[US] As a repository owner, I want to have a labeler action

Tasks:

• tupdate existings labels
• create action
• test

[US] As a developer, I want to have a front-end CI/CD

[US] As a developer, I want to have a golang cli as base project

Tasks:

• add golang env
• dockerize
• actions

[US] As a ops, I want to be able to terraform all my infrastructure

[US] As a developer, I want to be able to dockerize my application

Tasks:

• create a python default application
• create a Dockerfile
• add Docker doc to README

[US] As a developer, I want to have consistant workflows name

[US] As a repository owner, I want to have an accurate documentation

Tasks:

• Add badges to README
• Add Actions stuff
• Add goal + template use
• Add license

[US] As a repository owner, I want to create release with changelog

[US] As a ops, I want to have a Helm chart per service (web / api)

Tasks:

• web helm chart
• api helm chart

[US] As a repository owner, I want to be able to check my code with linting using GitHub Action

Tasks:

• Create a workflow file
• Create badge to the documentation

[US] As a developer, I want to have a /cmd folder to contain my main file

[US] As a repository owner, I want to be able to push my Docker image to GitHub Package Registry via GitHub Actions

Tasks:

• Create a workflow to build and push Docker image
• Assure the connexion between GitHub Actions and GitHub Package Registry
• Create badge to the documentation

[US] As a user, I want to have a web app connected to my Golang API

Tasks:

• add Vitejs bundle
• setup env vars
• lightweight

[US] As a repository owner, I want to have a basic doc in relation to the open source aspect of the project

Tasks:

• centralize md files
• contributing
• code of conduct

[US] As a ops, I want to have ops tools

Tasks:

• argocd
• fluxcd
• external secrets

[US] As a ops, I want to dockerize my front-end app

[US] As a developer, I want to have a clean Golang code

Tasks:

• remove / ehance Golang ORM
• adapt file / folder structure / conventions
• change gin-gonic for better framework

[US] As a ops, I want to have a Kubernetes cluster configuration

[US] As a repository owner, I want to be able to create a release filled with changelog using GitHub Action

Tasks:

• Find a GitHub Action to create a release
• Find a GitHub Action to fill the release body with changelogs
• Create badge to the documentation

[US] As a repository owner, I want to have a repo with folder name that make sense

https://github.com/golang-standards/project-layout

• set folders at root
• /bluid
• /deployment
• /vendor
• /app ??
• /scripts