## Creating, Upgrading, and Consuming Modules

In this "starter" example, we will demonstrate several important attributes of Go modules, including how modules:

* provide semantic versioning for a collection of related Go packages
* record precise dependencies
* provide for 100% reproducible builds
* allow upgrades for backwards compatable changes as well as breaking changes

## Example Overview

At different points in the walkthrough, we will adopt one of two different roles:

* **Module Publisher** – creates a `starterlib` module from scratch and releases several versions
* **Module Consumer** – imports and uses the `starterlib` module in a separate `starterconsumer` module

We pretend that time moves foward as the **Module Publisher**:
1. creates a v1.0.0 of `starterlib`
2. introduces new backwards compatible functionality in v1.1.0 of `starterlib`
3. introduces breaking changes in v2.0.0 of `starterlib`

At each step, the **Module Consumer** upgrades `starterconsumer` to use the new version of `starterlib`.

## Walkthrough

### Module Publisher: Create v1.0.0 of starterlib

First, **Module Publisher** creates a simple package that prints hello along
with a Go proverb in a `WiseHello` function.

setup starterlib:

```
{{PrintBlock "setup starterlib" -}}
```

define starterlib repo module:

```
{{PrintBlock "define starterlib repo module" -}}
```

write v1.0.0 code:

```
{{PrintBlock "write v1.0.0 code" -}}
```

build v1.0.0 code:

```
{{PrintBlock "build v1.0.0 code" -}}
```

init git:

```
{{PrintBlock "init git" -}}
```

tag v1.0.0:

```
{{PrintBlock "tag v1.0.0" -}}
```

### Module Consumer: Import and use v1.0.0 of starterlib

Now we switch roles to the **Module Consumer**, and create a separate
simple module that imports `starterlib`.

setup starterconsumer:

```
{{PrintBlock "setup starterconsumer" -}}
```

define starterconsumer repo module:

```
{{PrintBlock "define starterconsumer repo module" -}}
```

write v1.0.0 consumer:

```
{{PrintBlock "write v1.0.0 consumer" -}}
```

build and run v1.0.0 consumer:

```
{{PrintBlock "build and run v1.0.0 consumer" -}}
```

cat v1.0.0 consumer go.mod:

```
{{PrintBlock "cat v1.0.0 consumer go.mod" -}}
```

review v1.0.0 consumer versions:

```
{{PrintBlock "review v1.0.0 consumer versions" -}}
```

### Module Publisher: Create v1.1.0 of starterlib

Now the **Module Publisher** introduces new backwards compatible functionality in v1.1.0
of `starterlib`.

To make the example slightly more interesting, we create also introduce
a new `hello` package in `starterlib`, and refactor our initial `WiseHello` functionality
to use the new package while maintaining the exact behavior for `WiseHello` that we
had in v1.0.0 to maintain backwards compatibility.

add new package for v1.1.0 code:

```
{{PrintBlock "add new package for v1.1.0 code" -}}
```

review v1.1.0 code organization:

```
{{PrintBlock "review v1.1.0 code organization" -}}
```

refactor wise.go for v1.1.0 code:

```
{{PrintBlock "refactor wise.go for v1.1.0 code" -}}
```

build v1.1.0 code:

```
{{PrintBlock "build v1.1.0 code" -}}
```

commit changes:

```
{{PrintBlock "commit changes" -}}
```

tag v1.1.0:

```
{{PrintBlock "tag v1.1.0" -}}
```

### Module Consumer: Import and use v1.1.0 of starterlib

Now we switch roles back to the **Module Consumer** again, and
upgrade to use v1.1.0 of `starterlib` in the `starterconsumer` module.

rebuild consumer after publishing v1.1.0:

```
{{PrintBlock "rebuild consumer after publishing v1.1.0" -}}
```

cat consumer go.mod after publishing v1.1.0:

```
{{PrintBlock "cat consumer go.mod after publishing v1.1.0" -}}
```

review consumer upgrade versions after publishing v1.1.0:

```
{{PrintBlock "review consumer upgrade versions after publishing v1.1.0" -}}
```

upgrade to v1.1.0:

```
{{PrintBlock "upgrade to v1.1.0" -}}
```

rebuild consumer after upgrading to v1.1.0:

```
{{PrintBlock "rebuild consumer after upgrading to v1.1.0" -}}
```

review consumer upgrade versions after upgrading to v1.1.0:

```
{{PrintBlock "review consumer upgrade versions after upgrading to v1.1.0" -}}
```

### Module Publisher: Create v2.0.0 of starterlib

Now the **Module Publisher** breaks compatability by introducing new backwards _incompatible_
changes to `starterlib`

This triggers the need to:
 * increment the major release number
 * add `/v2` to the module path in the `module` directive in the `go.mod` for `starterlib`
 * add `/v2` to the import paths used internally for `starterlib`
 * release as v2.0.0

refactor wise.go for v2.0.0 code:

```
{{PrintBlock "refactor wise.go for v2.0.0 code" -}}
```

update go.mod for v2.0.0 code:

```
{{PrintBlock "update go.mod for v2.0.0 code" -}}
```

build v2.0.0 code:

```
{{PrintBlock "build v2.0.0 code" -}}
```

commit v2.0.0 changes:

```
{{PrintBlock "commit v2.0.0 changes" -}}
```

tag v2.0.0:

```
{{PrintBlock "tag v2.0.0" -}}
```

### Module Consumer: Import and use v2.0.0 of starterlib

Now we switch roles back to the **Module Consumer** one last time, and
upgrade to use v2.0.0 of `starterlib` in the `starterconsumer` module.

To do this, we need to:
 * add `/v2` to the module path in the `require` directive for `starterlib` in the `starterconsumer` `go.mod`
 * add `/v2` to the import path for `starterlib` in our `starterconsumer` code.

review consumer versions after publishing v2.0.0:

```
{{PrintBlock "review consumer versions after publishing v2.0.0" -}}
```

rebuild consumer after upgrading to v2.0.0:

```
{{PrintBlock "rebuild consumer after upgrading to v2.0.0" -}}
```

version details:

```
{{PrintBlock "version details" -}}
```