Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .golangci.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
linters-settings:
goimports:
local-prefixes: github.com/golang-templates/library
local-prefixes: github.com/golang-templates/seed
golint:
min-confidence: 0
misspell:
Expand Down
16 changes: 8 additions & 8 deletions .vscode/tasks.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,36 +4,36 @@
"version": "2.0.0",
"tasks": [
{
"label": "All",
"label": "all",
"type": "shell",
"command": "mage -v all",
"command": "make all",
"problemMatcher": [
"$go"
],
"group": "build"
},
{
"label": "Build",
"label": "build",
"type": "shell",
"command": "mage -v build",
"command": "make build",
"problemMatcher": [
"$go"
],
"group": "build"
},
{
"label": "Lint",
"label": "lint",
"type": "shell",
"command": "mage -v lint",
"command": "make lint",
"problemMatcher": [
"$go"
],
"group": "build"
},
{
"label": "Test",
"label": "test",
"type": "shell",
"command": "mage -v test",
"command": "make test",
"problemMatcher": [
"$go"
],
Expand Down
2 changes: 0 additions & 2 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
# go
FROM golang:1.14.2
# mage
RUN GO111MODULE=on go get github.com/magefile/mage@v1.9.0
# golangci-lint
RUN curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.26.0
28 changes: 28 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
.DEFAULT_GOAL := help

.PHONY: all
all: ## full build: build, lint, test
all: build lint test

.PHONY: build
build: ## go build
$(call print-target)
go build ./...

.PHONY: lint
lint: ## golangci-lint
$(call print-target)
golangci-lint run

.PHONY: test
test: ## go test with race detector and code covarage
$(call print-target)
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}'

define print-target
@echo "Executing target: \033[36m$@\033[0m"
endef
88 changes: 34 additions & 54 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,51 +1,63 @@
# Go Library Template
# Go Project 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)
[![Build Status](https://github.com/golang-templates/seed/workflows/build/badge.svg)](https://github.com/golang-templates/seed/actions?query=workflow%3Abuild)
[![GoDoc](https://godoc.org/github.com/golang-templates/seed?status.svg)](https://godoc.org/github.com/golang-templates/seed)
[![GitHub Release](https://img.shields.io/github/release/golang-templates/seed.svg)](https://github.com/golang-templates/seed/releases)
[![Go Report Card](https://goreportcard.com/badge/github.com/golang-templates/seed)](https://goreportcard.com/report/github.com/golang-templates/seed)

This is GitHub project template for a Go library. It has been created for ease-of-use for anyone who wants to:
This is GitHub project template for Go. 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.
- create a new repoisitory with basic Continous Integration.

It includes:

- [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).
- build automation via [Make](https://www.gnu.org/software/make), [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.

## Usage

1. Click the `Use this template` button (alt. clone or download this repository).
1. Replace all occurences of `golang-templates/library` to `your_org/repo_name` in all files.
1. Replace all occurences of `golang-templates/seed` to `your_org/repo_name` in all files.
1. Change [LICENSE](LICENSE) and [README.md](README.md).

### Setup Development Environment
### Setup Development Environment - 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.
#### Visual Studio Code - Bare-metal

- **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).
1. Install [Go](https://golang.org/doc/install) and [Go extension](https://code.visualstudio.com/docs/languages/go).
1. Visual Studio Code: `View` → `Command Pallete... (F1)` → Select `Go: Install/Update Tools`.
1. See [Dockerfile](Dockerfile) for GolangCI-Lint installation command.

#### Visual Studio Code - Development Container

1. [Setup Development inside a Container](https://code.visualstudio.com/docs/remote/containers#_getting-started).
1. Visual Studio Code inside Container: `View` → `Command Pallete... (F1)` → Select `Go: Install/Update Tools`.
1. See [Dockerfile](Dockerfile) for GolangCI-Lint installation command.

#### Visual Studio Code - SSH

1. [Setup Remote Development using SSH](https://code.visualstudio.com/docs/remote/ssh#_getting-started).
1. On remote machine: install [Go](https://golang.org/doc/install) and [Go extension](https://code.visualstudio.com/docs/languages/go).
1. Visual Studio Code: `View` → `Command Pallete... (F1)` → Select `Go: Install/Update Tools`.
1. See [Dockerfile](Dockerfile) for GolangCI-Lint installation command.

### Build

- Terminal: `mage -v all`.
- Terminal: `make all`.
- Visual Studio Code: `Terminal` → `Run Build Task... (CTRL+ALT+B)` → Select `All`.
- Terminal: `docker-compose up --abort-on-container-exit`. This command is executed by CI build (GitHub Action workflow).

### Maintainance

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. Update Go and GolangCI-Lint version in [Dockerfile](Dockerfile).
1. Configure linters via [.golangci.yml](.golangci.yml).
1. Develop Mage targets in [magefile.go](magefile.go) and assosiated tasks in [.vscode/tasks.json](.vscode/tasks.json).
1. Develop Make targets in [Makefile](Makefile) and assosiated tasks in [.vscode/tasks.json](.vscode/tasks.json).

Notable files:

Expand All @@ -55,49 +67,17 @@ Notable 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)
- [Makefile](Makefile) - Make 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`.
### Make does not work on Windows

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).
You can use [WSL (Windows Subsystem for Linux)](https://docs.microsoft.com/en-us/windows/wsl/install-win10) or try [Make Windows port](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).
The maintainer does not use GoLand. Fell free to create a pull request for [#2](https://github.com/golang-templates/seed/issues/2).

### Why GitHub Actions, not any other CI server

Expand Down
3 changes: 1 addition & 2 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ services:
container_name: builder
build: .
working_dir: /app
command: mage -v all
command: make all
volumes:
- $PWD:/app

4 changes: 2 additions & 2 deletions foo.go
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// Package library has a dummy function covered by a unit test.
package library
// Package seed has a dummy function covered by a unit test.
package seed

// Foo returns "Bar".
func Foo() string {
Expand Down
4 changes: 2 additions & 2 deletions foo_test.go
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
package library_test
package seed_test

import (
"testing"

. "github.com/golang-templates/library"
. "github.com/golang-templates/seed"
)

func TestFoo(t *testing.T) {
Expand Down
4 changes: 1 addition & 3 deletions go.mod
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
module github.com/golang-templates/library
module github.com/golang-templates/seed

go 1.14

require github.com/magefile/mage v1.9.0
2 changes: 0 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
@@ -1,2 +0,0 @@
github.com/magefile/mage v1.9.0 h1:t3AU2wNwehMCW97vuqQLtw6puppWXHO+O2MHo5a50XE=
github.com/magefile/mage v1.9.0/go.mod h1:z5UZb/iS3GoOSn0JgWuiw7dxlurVYTu+/jHXqQg881A=
28 changes: 0 additions & 28 deletions magefile.go

This file was deleted.