add github actions for PR checks and adding zip builds to releases (#1)

Author: Dan Brakeley

.github/workflows/release.yaml

@@ -0,0 +1,20 @@
+name: build release zip
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  release:
+    name: Release Go Binary
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+      - uses: wangyoucao577/go-release-action@v1.20
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          goos: windows
+          goarch: amd64
+          goversion: "1.17.2"
+          project_path: "./cmd/p4harmonize"
+          extra_files: LICENSE.txt README.md

.github/workflows/test.yaml

@@ -0,0 +1,16 @@
+name: validate commit
+on: [pull_request]
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-20.04, windows-2019]
+        go-ver: [1.17.2]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-go@v2
+        with:
+          go-version: ${{ matrix.go-ver }}
+      - run: go test ./...
+      - run: go build ./cmd/p4harmonize

README.md

@@ -4,7 +4,7 @@
 
 `p4harmonize` is a tool for getting the head revision of a stream on one perforce server to mirror the head revision from some other perforce server. It can reconcile files, fix differences in file name/path capitalization, fix the file type, and fix improperly checked in AppleDouble files created by the "apple" file type.
 
-`p4harmonize` was built with Unreal Engine releases in mind, where the Epic licensee perforce server is used as the source, and a dedicated stream on a project's perforce server is used as the destination. It is intended to be used with a setup similar to [the one recommended by Epic](https://docs.unrealengine.com/4.26/en-US/ProgrammingAndScripting/ProgrammingWithCPP/DownloadingSourceCode/UpdatingSourceCode/#option3:usingperforce). At Proletariat, we have different names, but the purposes are the same:
+`p4harmonize` was built with Unreal Engine releases in mind, where the Epic licensee perforce server is used as the source, and a dedicated stream on a project's perforce server is used as the destination. It is intended to be used with a setup similar to [the one recommended by Epic](https://docs.unrealengine.com/4.26/en-US/ProgrammingAndScripting/ProgrammingWithCPP/DownloadingSourceCode/UpdatingSourceCode/#integrating,merging,andbranching). At Proletariat, we have different names, but the purposes are the same:
 
 name | description
 --- | ---
@@ -14,15 +14,17 @@ name | description
 
 ## Install
 
-There's no pre-packaged binaries at this point, so you'll need to build one yourself. To do that, you'll need [git](https://git-scm.com/downloads) and a [recent version of Go](https://golang.org/dl/), and then you can just use the [go install](https://golang.org/ref/mod#go-install) command to download, build, and put the result in your path:
+You can download the latest Windows executable from the [releases page](https://github.com/proletariatgames/p4harmonize/releases), or you can build it yourself.
+
+To build it, you'll need [git](https://git-scm.com/downloads) and a [recent version of Go](https://golang.org/dl/), and then you can just use the [go install](https://golang.org/ref/mod#go-install) command to download, build, and put the result in your path:
 
 ```text
 go install github.com/proletariatgames/p4harmonize
 ```
 
 ## Usage
 
-`p4harmonize` pulls configuration from a `config.toml` file, which it looks for in the current folder. You can change where it looks by passing `-config <filename>`.
+`p4harmonize` pulls configuration from a `config.toml` file, which it looks for in the current working directory. You can change where it looks by passing `-config <filename>`.
 
 Here's an example `config.toml` file:
 
@@ -46,7 +48,7 @@ new_client_stream = "//test/engine_epic"  # this needs to already exist
 
 While it runs, it outputs status updates and every individual `p4` command it is running so you can follow along. Note that for an Unreal Engine upgrade, this process can easily take hours to complete.
 
-When it is done, you still need to go in and submit the changelist it created yourself. This gives you an opportunity to sanity check the work before it gets added to your Perforce depot. This also allows you to keep the destination locked until the moment you are ready to submit the changes.
+When it is done, you still need to go in and submit the changelist it created yourself. This gives you an opportunity to sanity check the work before it gets added to your Perforce depot.
 
 ## Runtime requirements
 
@@ -62,7 +64,7 @@ When it is done, you still need to go in and submit the changelist it created yo
 
 ## Development setup
 
-To write code and create builds, you just need the deps listed above (git, Go, p4, and bash). If you want to run the functional tests, where p4harmonize is run against two test Perforce servers, you will also need Docker. On Windows and Mac, you'll want [Docker Desktop](https://www.docker.com/products/docker-desktop), and on Linux you'll want [Docker Server](https://docs.docker.com/engine/install/#server).
+To write code and create builds, you just need the deps listed above (git, Go, p4, and bash). If you want to run the functional tests, you will also need Docker. On Windows and Mac, you'll want [Docker Desktop](https://www.docker.com/products/docker-desktop), and on Linux you'll want [Docker Server](https://docs.docker.com/engine/install/#server).
 
 Once you have all that installed, you can clone down the source code with git:
 
@@ -80,16 +82,16 @@ There's a `magefile.go` in the root folder that automates building/testing, and
 $ mage
 Targets:
   build       tests and builds the app (output goes to "local" folder)
-  longTest    Runs integration tests (spins up perforce servers via docker, then brings them down at the end).
-  run         unit tests, builds, and runs the app
-  testDown    kills and deletes the test perforce servers.
-  testPrep    gets everything ready for a run against test servers, and can be used to reset test servers after a test run.
-  testUp      brings up a test environment with two perforce servers, on ports 1667 and 1668, to act as the source and destination perforce servers for testing p4harmonize.
+  longTest    runs a fresh build of p4harmonize against test files in docker-hosted perforce servers.
+  run         runs unit tests, builds, and runs the app
+  testDown    brings down and removes the docker contains started by TestUp.
+  testPrep    runs testDown, then testUp, then executes `test/prop.sh` to fill the servers with test data.
+  testUp      brings up two empty perforce servers via Docker, listening on ports 1667 and 1668, with a single super user named "super" (no password).
 ```
 
-Note that mage target names are not case sensitive, ie `mage longTest` and `mage longtest` will all do the same thing.
+Note that mage target names are not case sensitive, ie `mage longTest` and `mage longtest` are interpreted the same.
 
-If you see "No .go files marked with the mage build tag in this directory", make sure you there is a `magefile.go` in the current folder (`mage` does not look to parent folders for magefiles).
+If you see `No .go files marked with the mage build tag in this directory`, make sure you there is a `magefile.go` in the current folder (Mage does not look to parent folders for magefiles).
 
 The `build` and `run` targets will run unit tests and build an executable in a folder named `local` (which is where it will look for a `config.toml` file).
 

magefile.go

@@ -32,7 +32,7 @@ func Build() {
 	sh.Cmdf("go build -o local/%s ./cmd/%s", target, cmd).Run()
 }
 
-// Run unit tests, builds, and runs the app
+// Run runs unit tests, builds, and runs the app
 func Run() {
 	mg.Deps(Build)
 
@@ -44,15 +44,15 @@ func Run() {
 	})
 }
 
-// Runs integration tests (spins up perforce servers via docker, then brings them down at the end).
+// LongTest runs a fresh build of p4harmonize against test files in docker-hosted perforce servers.
 func LongTest() {
 	mg.SerialDeps(Build, TestPrep)
 	defer TestDown()
 
 	target := sh.ExeName(cmd)
 
 	sh.InDir("local", func() {
-		sh.Echo("Running integration tests...")
+		sh.Echo("Running p4harmonize against test servers...")
 		sh.Cmdf("%s -config ../test/config.toml", target).Run()
 	})
 	sh.InDir("test", func() {
@@ -69,28 +69,29 @@ func LongTest() {
 	sh.Echo("***")
 }
 
-// TestPrep gets everything ready for a run against test servers, and can
-// be used to reset test servers after a test run.
+// TestPrep runs testDown, then testUp, then executes `test/prop.sh` to fill the servers with test data.
 func TestPrep() {
 	mg.SerialDeps(TestDown, TestUp)
+	sh.InDir("test", func() {
+		sh.Echo("Running test/prep.sh...")
+		sh.Cmdf("./prep.sh").Bash()
+	})
 	sh.RemoveAll("./local/p4/dst")
 }
 
-// TestUp brings up a test environment with two perforce servers, on ports 1667 and 1668, to act as the
-// source and destination perforce servers for testing p4harmonize.
+// TestUp brings up two empty perforce servers via Docker, listening on ports 1667 and 1668, with
+// a single super user named "super" (no password).
 func TestUp() {
 	sh.InDir("test", func() {
-		sh.Echo("Running docker compose...")
+		sh.Echo("Bringing up test perforce servers on local ports 1667 and 1668...")
 		sh.Cmdf("docker compose up --detach --force-recreate --build").Run()
-		sh.Echo("Running prep.sh...")
-		sh.Cmdf("./prep.sh").Bash()
 	})
 }
 
-// TestDown kills and deletes the test perforce servers.
+// TestDown brings down and removes the docker contains started by TestUp.
 func TestDown() {
 	sh.InDir("test", func() {
-		sh.Echo("Stopping and removing containers...")
+		sh.Echo("Stopping and removing test perforce servers...")
 		sh.Cmdf("docker compose stop -t 1").Run()
 		sh.Cmdf("docker compose rm -f").Run()
 	})