GitHub - go-modules-by-example/index: Go modules by example is a series of work-...

README.md

Go modules by example

Go modules by example is a series of work-along guides that look to help explain how go modules works and how to get things done.

• The go modules tour (a rewrite of the original vgo tour)
• Using go modules with gopkg.in
• Migrating Buffalo from dep to go modules
• Using a package that has not been converted to go modules
• Example of backwards compatability in Go 1.10 with semantic import paths
• Another example of package/project that has not yet been converted to a module
• Forking a project which has not yet been converted to a Go module
• Using modules to generate a vendor
• How to use submodules
• Tools as dependencies
• Using gohack to "hack" on dependencies
• Creating a module download cache "vendor"
• Cyclic module dependencies
• ...

See the Feedback and TODO wiki for more up-to-date commentary.

Structure

A guide simply comprises a README.md and an accompanying bash script. The README is the human readable bit and the script acts as a reproducible set of steps (that can be tested) for the guide. For example, the vgo tour has been rewritten as a Go modules by example guide:

$ ls 001_go_modules_tour
README.md
script.sh

script.sh contains, as its name suggests, the overall script for the guide. It includes a pre-amble that defines a number of helper functions for testing the script, followed by the header:

# **START**

This marks the start of the script.

What follows are a number of optionally commented "blocks". For example, the following block is labelled "install tools" and comprises all the contiguous lines that follow the special # block: comment:

# block: install tools
go install example.com/blah
assert "$? -eq 0" $LINENO

Assertions can be made within the script to ensure that everything is still "on track".

The corresponding README.md acts as a template for the guide itself, but crucially it can reference these blocks to include the commands themselves and/or their output, e.g.:

```
{{PrintBlock "install tools" -}}
```

Look at the raw Go modules by example tour README.md and corresponding script for more examples.

Testing scripts

To ensure reproducibility and isolation, scripts are run in a Docker container; the golang container is used:

docker pull golang

The following environment variables must be set:

GITHUB_USERNAME    # your Github username
GITHUB_PAT         # a personal access token with public_repo scope
GITHUB_ORG         # an org/user account where forks, examples will be created
GITHUB_ORG_ARCHIVE # an org/user account where old forks, examples etc will be moved

Create a new personal access token.

Ensure egrunner is installed (and on your PATH):

go install myitcv.io/go-modules-by-example/cmd/egrunner

Now run in debug mode to see real-time output:

egrunner -out debug ./001_go_modules_tour/script.sh

Regenerating a guide

First ensure mdreplace and egrunner are installed (and on your PATH):

go install myitcv.io/go-modules-by-example/cmd/egrunner myitcv.io/go-modules-by-example/cmd/mdreplace

Then re-run mdreplace on a guide template, e.g. for the go modules by example tour:

mdreplace -w -long -online ./001_go_modules_tour/README.md

Caveats

This project is:

• work-in-progress
• pending review
• likely to move somewhere else