Tutorial

Note

Do you find any of these instructions confusing? Edit this file and submit a pull request with your improvements!

To start with, you will need a GitHub account. Create this before you get started with this tutorial. If you are new to Git and GitHub, you should probably spend a few minutes on some of the tutorials at the top of the page at GitHub Help.

🍪 Step 1: Install Cookiecutter

Install cookiecutter>=1.4.0:

$ python3 -m pip install -U cookiecutter>=1.4.0

We’ll also need pre-commit, bump2version and a few other tools for initializing the new project:

$ python3 -m pip install pre-commit bump2version invoke ruamel.yaml halo

As part of the pre-commit hooks, some golang tools are run. Those must also be installed:

$ go get -u golang.org/x/tools/cmd/goimports
$ go get -u golang.org/x/lint/golint
$ go get -u github.com/fzipp/gocyclo/cmd/gocyclo
$ go get -u github.com/mitchellh/gox  # if you want to test building on different architectures and platforms

Warning

To be able to excecute the tools downloaded with go get, make sure to include $GOPATH/bin in your $PATH. If echo $GOPATH does not give you a path make sure to set it (export GOPATH="$HOME/go" for example). On order for your changes to persist, do not forget to add these to your shells .bashrc.

📦 Step 2: Generate Your Go Project

Now it’s time to generate your golang project.

Use cookiecutter, pointing it at the cookiecutter-go repo:

$ cookiecutter https://github.com/romnnn/cookiecutter-go.git

You’ll be asked to enter a bunch of values to set the package up. If you don’t know what to enter, stick with the defaults.

🐙 Step 3: Create a GitHub Repo

Go to your GitHub account and create a new repo named mypackage, where mypackage matches the [project_slug] from your answers to running cookiecutter. This is so that Travis CI can find it when we get to Step 5.

You will find one folder named after the [project_slug]. Move into this folder, and then setup git to use your GitHub repo and upload the code:

$ cd <mypackage>
$ git remote add origin git@github.com:myusername/mypackage.git
$ git add .
$ pre-commit run --all-files
$ git add .
$ git commit -m "Initial commit"
$ git push --set-upstream origin master

Where myusername and mypackage are adjusted for your username and package name.

You can use HTTPS to push the repository, but it’s more convenient to use a ssh key to push the repo. You can generate a key or add an existing one.

🛠️ Step 4: First build

You should still be in the folder containing the go.mod file.

Go ahead and give building the initial project a go (no pun intended):

$ go build <your-package>

You can also test the entire project by running the pre commit hooks, which should have been installed into your git repository:

$ invoke pre-commit

Next to building, this will also format and lint your code amongst other things.

👷 Step 5: Set up TravisCI

Travis-CI * is a continuous integration tool used to prevent integration problems. Every commit to the master branch will trigger automated builds of the application.

Add the repository to your Travis-CI account by activating it. If you have connected travis with GitHub this is done automatically. If you have not yet installed the Travis CLI (Command line interface), follow the installation guide.

With the Travis CLI, setup automatic upload of binaries to GitHub releases by entering:

$ travis login
$ travis setup releases         # When using travis.org
$ travis setup releases --com   # When using travis.com

Note

Both commands will ask you for your GitHub credentials. If you are worried, skip travis login, create a GitHub token manually and use travis encrypt. This is not part of the tutorial.

After running setup releases, your .travis.yml config will:

• include the encrypted GitHub OAuth token

• be able to automatically deploy binaries to releases when you push a new tag to the master branch.

Because the token is appended outside of any build stage, you still need to manually edit the .travis.yml config or run:

$ invoke fix-token

If you do not want to publish pre-built releases, remove the Publish release stage in .travis.yml.

*

Private projects will be on travis-ci.com, public ones on travis-ci.org. This has long been a thing, but afaik all projects should use travis-ci.com as of now?

🐳 Step 6: Setup docker

If you want to publish the tool as a docker container, connect hub.docker.com with your GitHub account and create a new repository.

Make sure to choose a matching name and connect your GitHub repository at the bottom of the page. You must also specify the location of the Dockerfile (choose the default /). When you are done click Create and build.

🎉 Step 7: Start coding!

Hopefully this tutorial was helpful to you!