diff --git a/Dockerfile b/Dockerfile index 27049ba..1d4bc53 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -# Go +# go FROM golang:1.14.2 # mage RUN GO111MODULE=on go get github.com/magefile/mage@v1.9.0 diff --git a/README.md b/README.md index ba7ebf4..e63a6b0 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,22 @@ +# Go Library Template + [![Build Status](https://github.com/golang-templates/library/workflows/build/badge.svg)](https://github.com/golang-templates/library/actions?query=workflow%3Abuild) [![GoDoc](https://godoc.org/github.com/golang-templates/library?status.svg)](https://godoc.org/github.com/golang-templates/library) [![GitHub Release](https://img.shields.io/github/release/golang-templates/library.svg)](https://github.com/golang-templates/library/releases) [![Go Report Card](https://goreportcard.com/badge/github.com/golang-templates/library)](https://goreportcard.com/report/github.com/golang-templates/library) -# Go Library Template - This is GitHub project template for a Go library. It has been created for ease-of-use for anyone who wants to: - quickly get into Go without losing too much time on environment setup, - create a new repoisitory with basic Continous Integration, -- write Go code on Linux, MacOS, Windows, -- use free tools. +- write Go code on Linux, MacOS, Windows. It includes: -- editor config: [Visual Studio Code](https://code.visualstudio.com) with [Go](https://code.visualstudio.com/docs/languages/go) and [Remote Container](https://code.visualstudio.com/docs/remote/containers) support, -- dependency management: [Go Modules](https://github.com/golang/go/wiki/Modules), -- linter: [GolangCI-Lint](https://github.com/golangci/golangci-lint), -- build automation: [Mage](https://magefile.org), [Docker](https://docs.docker.com/engine), [Docker Compose](https://docs.docker.com/compose), [GitHub Actions](https://github.com/features/actions). +- [Visual Studio Code](https://code.visualstudio.com) configuration with [Go](https://code.visualstudio.com/docs/languages/go) and [Remote Container](https://code.visualstudio.com/docs/remote/containers) support, +- dependency management using [Go Modules](https://github.com/golang/go/wiki/Modules), +- linting with [GolangCI-Lint](https://github.com/golangci/golangci-lint), +- build automation via [Mage](https://magefile.org), [Docker](https://docs.docker.com/engine), [Docker Compose](https://docs.docker.com/compose), [GitHub Actions](https://github.com/features/actions). `Star` this project if you find it valuable and worth maintaining. @@ -29,10 +28,10 @@ It includes: ### Setup Development Environment -Take notice that this project is build in a way that gives the developer a lot of freedom on the development environment setup. Below you can find proposals when using Visual Studio Code. +Take notice that this project is build in a way that gives developers a lot of freedom on development environments setup. Below you can find proposals when using Visual Studio Code. -- **Bare metal:** Install Go, Visual Studio Code, Mage and GolangCI-Lint (see [Dockerfile](Dockerfile) for Mage and GolangCI-Lint installation commands). -- **Containers:** Install Docker, Visual Studio Code with Remote - Container extension. [Instructions](https://code.visualstudio.com/docs/remote/containers). +- **Bare metal:** See [Dockerfile](Dockerfile) for Mage and GolangCI-Lint installation commands. +- **Containers:** [Instructions](https://code.visualstudio.com/docs/remote/containers). - **Remote via SSH**: [Instructions](https://code.visualstudio.com/docs/remote/ssh). ### Build @@ -46,7 +45,77 @@ Take notice that this project is build in a way that gives the developer a lot o 1. `Watch` this project to get notified about new releases, issues, etc. 1. Update Go, Mage and GolangCI-Lint version in [Dockerfile](Dockerfile). Take notice that when working on bare metal or via SSH, then you should also to do it manually on your machine. 1. Configure linters via [.golangci.yml](.golangci.yml). -1. Develop tasks/targets in [magefile.go](magefile.go) and [.vscode/tasks.json](.vscode/tasks.json). +1. Develop Mage targets in [magefile.go](magefile.go) and assosiated tasks in [.vscode/tasks.json](.vscode/tasks.json). + +Notable files: + +- [devcontainer.json](.devcontainer/devcontainer.json) - Visual Studio Code Remote Container configuration +- [.github](.github/workflows/build.yml) - GitHub Action workflow (CI build) +- [.vscode](.vscode) - Visual Studio Code configuration files +- [.golangci.yml](.golangci.yml) - GolangCI-Lint configuration +- [docker-compose.yml](docker-compose.yml) - Compose file used in [CI build](.github/workflows/build.yml) +- [Dockerfile](Dockerfile) - Builder image used in [docker-compose.yml](docker-compose.yml) and [devcontainer.json](.devcontainer/devcontainer.json) +- [magefile.go](magefile.go) - Mage targets used in [docker-compose.yml](docker-compose.yml) and [.vscode/tasks.json](.vscode/tasks.json) + +## FAQ + +### Why Mage instead of Make + +Here is [why](https://github.com/magefile/mage#why). +However, updating to Make is pretty straightforward. + +1. Replace [magefile.go](magefile.go) with a `Makefile` file: + +```make +.DEFAULT_GOAL := help + +.PHONY: all +all: ## full build: build, lint, test +all: build lint test + +.PHONY: build +build: ## go build + go build ./... + +.PHONY: lint +lint: ## golangci-lint + golangci-lint run + +.PHONY: test +test: ## go test with race detector and code covarage + go test -race -covermode=atomic + +.PHONY: help +help: + @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' +``` + +2. Remove Mage installation from [Dockerfile](Dockerfile). +1. Update [docker-compose.yml](docker-compose.yml) and [.vscode/tasks.json](.vscode/tasks.json) to use `make`. + +If you want to use Make on bare-metal Windows, then you can use [WSL (Windows Subsystem for Linux)](https://docs.microsoft.com/en-us/windows/wsl/install-win10) or install [Make Windows port to Git Bash](https://gist.github.com/evanwill/0207876c3243bbb6863e65ec5dc3f058). + +### Why nothing for GoLand + +The maintainer does not use GoLand. Fell free to create a pull request for [#2](https://github.com/golang-templates/library/issues/2). + +### Why GitHub Actions, not any other CI server + +GitHub Actions is out-of-the-box if you are already using GitHub. +However, changing to any other CI server should be very simple, because this repository uses Docker Compose to run CI build to make the transition easy. + +For [CircleCI](https://circleci.com/docs/2.0/executor-types/#using-machine) create `.circleci/config.yml` file: + +```yml +version: 2.1 +jobs: + build: + machine: + image: ubuntu-1604:201903-01 + steps: + - checkout + - run: docker-compose up --abort-on-container-exit +``` ## Contributing