workflow & doc improvements (#11)

* attempt experimental windows builds
* leave win builds disabled and improve docs a bit
* create goreleaser workflow but skip publish for now
* change snapshot name template for better archive filenames

.github/workflows/release.yml

@@ -0,0 +1,35 @@
+---
+name: release
+
+on:
+  workflow_run:
+    workflows: ["test"]
+    branches: [main]
+    types:
+      - completed
+
+jobs:
+  release:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - name: setup-go
+        uses: actions/setup-go@v2
+        with:
+          go-version: 1.16.x
+
+      - name: goreleaser
+        uses: goreleaser/goreleaser-action@v2
+        with:
+          distribution: goreleaser
+          version: latest
+          args: release --rm-dist --skip-publish
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -1,32 +1,50 @@
 ---
-"on":
+name: test
+
+on:
   push:
     branches: [main]
   pull_request:
     branches: [main]
-name: test
+
 jobs:
   test:
     strategy:
       matrix:
         go-version: [1.16.x]
-        tf-version: [0.12.x, latest]
-        os:
-          - ubuntu-latest
-          - macos-latest
-          # win support is not quite there yet.
-          #- windows-latest
+        tf-version: [latest, 0.12.x]
+        os: [macos-latest, ubuntu-latest]
+        experimental: [false]
+
+        # including these is non-ideal while windows support is questionable.
+        # even when continue-on-error=true they turn the PR checks red
+        #
+        # include:
+        #   - go-version: 1.16.x
+        #     tf-version: latest
+        #     os: windows-latest
+        #     experimental: true
+        #   - go-version: 1.16.x
+        #     tf-version: 0.12.x
+        #     os: windows-latest
+        #     experimental: true
+
     runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.experimental }}
+
     steps:
-      - name: setup go
+      - name: checkout
+        uses: actions/checkout@v2
+
+      - name: setup-go
         uses: actions/setup-go@v2
         with:
           go-version: ${{ matrix.go-version }}
-      - name: setup terraform
+
+      - name: setup-terraform
         uses: hashicorp/setup-terraform@v1
         with:
           terraform_version: ${{ matrix.tf-version }}
-      - name: checkout
-        uses: actions/checkout@v2
-      - name: test
+
+      - name: run-tests
         run: make test

.goreleaser.yml

@@ -1,32 +1,35 @@
-before:
-  hooks:
-    - make clean
-    - make tidy
-    - go generate ./...
 builds:
   - env:
       - CGO_ENABLED=0
     goos:
       - linux
-      - windows
       - darwin
       - freebsd
       - openbsd
       - solaris
+      ## windows support is still iffy
+      #- windows
     main: ./cmd/terrajux
-    ldflags: -s -w -X github.com/rhenning/terrajux.Version={{.Version}}
+    ldflags: >-
+      -s -w -X
+      github.com/rhenning/terrajux.Version={{.Version}}
+
 archives:
-  ## may enable these, but leaving disabled atm to align w/ terraform
-  # - replacements:
-  #     darwin: Darwin
-  #     linux: Linux
-  #     windows: Windows
-  #     386: i386
-  #     amd64: x86_64
+  - wrap_in_directory: true
+    format_overrides:
+      - goos: windows
+        format: zip
+    ## may enable these, but leaving disabled atm to align w/ terraform
+    # - replacements:
+    #     darwin: Darwin
+    #     linux: Linux
+    #     windows: Windows
+    #     386: i386
+    #     amd64: x86_64
 checksum:
   name_template: 'checksums.txt'
 snapshot:
-  name_template: "{{.Tag}}-snapshot+{{.Timestamp}}.{{.ShortCommit}}"
+  name_template: "{{.Tag}}-snapshot-{{.Timestamp}}-{{.ShortCommit}}"
 changelog:
   sort: asc
   filters:

README.md

@@ -10,14 +10,28 @@
 -->
 
 `terrajux` [diff](https://en.wikipedia.org/wiki/Diff)s the source code of a
-[Terraform](https://github.com/hashicorp/terraform)
+[terraform](https://github.com/hashicorp/terraform)
 [root module](https://www.terraform.io/docs/language/modules/index.html#the-root-module) project,
 along with the source of all its transitive module dependencies, between two git refs.
 
 
 ## how?
 
-try it!
+- ensure that `terraform` and `git` are installed and available in your system's `PATH`.
+- download the [latest release archive](https://github.com/rhenning/terrajux/releases/)
+  named for the os and arch appropriate for your system.
+- decompress and extract the archive.
+  - `tar -zxvf terrajux_<version>_<os>_<arch>.tar.gz` will do on many systems.
+- `terrajux` is distributed as a self-contained binary. simply move the `terrajux`
+  binary to a location of your choosing. for many, this will be somewhere in your
+  system's `PATH` such as `/usr/local/bin/` or `~/bin/`.
+- on macos it may be necessary to explictly inform the system that `terrajux` is
+  an approved program.
+  - navigate to the directory containing `terrajux` via terminal or finder.
+  - run `open .` if using the terminal.
+  - right-click on `terrajux` and select **open**.
+
+**try it!**
 
 ```
 terrajux giturl v1ref v2ref [subpath]
@@ -83,6 +97,26 @@ also, many of the tools intended for use within the terraform ecosystem have nam
 
 _juxtapose_ popped into my head while considering the possibilities, and so we have `terrajux`.
 
+
 ## license
 
 this project is released under the [apache 2.0 license](LICENSE).
+
+
+## faq
+
+> what is happening behind the scenes?
+
+in short, `terrajux`:
+- performs shallow clones of the the specified git repository at
+  the supplied refs
+- initializes terraform with `-backend=false` to download all module
+  dependencies without touching the terraform state backend
+- displays a recursive diff of the initialized projects
+
+
+> what platforms are supported?
+
+- macos and linux builds are fully tested for every pr and release
+- *bsd and solaris builds are untested but _should_ work
+- windows builds are disabled pending [some portability issues](https://github.com/rhenning/terrajux/issues)

TODO.md

@@ -7,18 +7,13 @@
       improve tests and avoid calling code with side effects
     * abstract external command executor via its own package
 * delivery
-    * consider github actions after better mocks & stubs
-    * consider goreleaser for build/release management
-    * test, vet, fmt, static analysis checks
     * homebrew
 * documentation
     * use concrete example based on fixtures in "try it"
     * add godoc to packages
     * named return values on all functions
     * consider additional documentation
     * contributing guidelines
-    * github metadata files
-    * FAQ
 * configuration
     * expose configuration overrides (difftool, terraform) to user
 * errors