Document version policy, add version subcommand

HISTORY.md

@@ -0,0 +1,36 @@
+Release Notes
+=============
+
+The CLI tool and library are versioned independently and both adhere to
+[Semantic Versioning] policy. Compatibility with Kafka Connect API versions
+will be noted in the release history below.
+
+Status
+------
+
+The library is tentatively at 1.0 status pending a trial release, the API is
+expected to be stable without breaking changes for the Kafka 0.10.0.x series.
+The CLI's output, exit codes, etc. are provisional and subject to change until
+a 1.0 release—please consult the change log before installing new versions if
+you rely on these for scripting.
+
+kafka-connect CLI
+-----------------
+
+### v0.9.0 - 11 August, 2016 ###
+
+**Library version: v0.9.0**
+
+Initial release. Covers nearly all API functionality (minus connector plugins),
+but output may not yet be stable.
+
+go-kafka/connect Library
+------------------------
+
+### v0.9.0 - 11 August, 2016 ###
+
+Initial release. Supports the Kafka Connect REST API as of Kafka v0.10.0.0.
+
+
+[Semantic Versioning]: http://semver.org/
+<!-- vim:set tw=79: -->

README.md

@@ -1,6 +1,7 @@
 Kafka Connect CLI
 =================
 
+[![Release][release-badge]][latest release]
 [![Build Status][travis-badge]][build status]
 [![Coverage Status][coverage-badge]][coverage status]
 [![Go Report Card][go-report-badge]][go report card]
@@ -12,13 +13,14 @@ through runbooks of `curl` commands when something's going wrong, or ever
 really.
 
 This project also contains a Go library for the Kafka Connect API usable by
-other Go-based tools or applications. See below for details.
+other Go tools or applications. See [Using the Go
+Library](#using-the-go-library) for details.
 
 Usage
 -----
 
 The tool is self-documenting: run `kafka-connect help` or `kafka-connect help
-<subcommand>` when you need a reference.
+<subcommand>` when you need a reference. A summary of functionality:
 
     $ kafka-connect
     usage: kafka-connect [<flags>] <command> [<args> ...]
@@ -68,6 +70,9 @@ The tool is self-documenting: run `kafka-connect help` or `kafka-connect help
       restart <name>
         Restart a connector and its tasks.
 
+      version
+        Shows kafka-connect version information.
+
 For examples, see [the Godoc page for the command][cmd doc].
 
 The process exits with a zero status when operations are successful and
@@ -84,6 +89,14 @@ If you'd like a `man` page, you can generate one and place it on your
 $ kafka-connect --help-man > /usr/local/share/man/man1/kafka-connect.1
 ```
 
+### Options ###
+
+Expanded details for select parameters:
+
+- `--host / -H`: API host address, default `http://localhost:8083/`. Can be set
+  with environment variable `KAFKA_CONNECT_CLI_HOST`. Note that you can target
+  any host in a Kafka Connect cluster.
+
 Installation
 ------------
 
@@ -132,8 +145,8 @@ would like a binary build for a platform that is not currently published, I'm
 happy to make one available as long as Go can cross-compile it without
 problem—please open an issue.*
 
-To build your own version from source, see the below *Building and Development*
-section.
+To build your own version from source, see the below [Building and
+Development](#building-and-development) section.
 
 ### Command Completion ###
 
@@ -146,18 +159,6 @@ which kafka-connect >/dev/null && eval "$(kafka-connect --completion-script-bash
 
 Predictably, use `--completion-script-zsh` for zsh.
 
-Options
--------
-
-Expanded details for select parameters, including supported environment
-variables:
-
-- `--host / -H`: API host address, default `http://localhost:8083/`. Supports
-  environment variable `KAFKA_CONNECT_CLI_HOST`. Note that you can target any
-  host in a Kafka Connect cluster.
-
-Others? `CLASSPATH` that the shell scripts support for connector plugins.
-
 Building and Development
 ------------------------
 
@@ -216,6 +217,12 @@ installed unless you append `/...` to the `go get` command above).
 
 See the API documentation linked above for examples.
 
+Versions
+--------
+
+For information about versioning policy and compatibility status please see
+[the release notes](HISTORY.md).
+
 Alternatives
 ------------
 
@@ -234,7 +241,13 @@ Kudos to the kafka-connect-tools authors for inspiration.
 Contributing
 ------------
 
-Please see [the Contributing Guide](CONTRIBUTING.md).
+Please see [the Contributing Guide](CONTRIBUTING.md)!
+
+License
+-------
+
+The library and CLI tool are made available under the terms of the MIT license,
+see the [LICENSE](LICENSE) file for full details.
 
 
 [Kafka Connect]: http://docs.confluent.io/current/connect/intro.html
@@ -246,6 +259,8 @@ Please see [the Contributing Guide](CONTRIBUTING.md).
 [ginkgo cli]: https://onsi.github.io/ginkgo/#the-ginkgo-cli
 [glide execs]: https://github.com/Masterminds/glide/pull/331
 
+[release-badge]: https://img.shields.io/github/release/go-kafka/connect.svg?maxAge=2592000
+[latest release]: https://github.com/go-kafka/connect/releases/latest
 [travis-badge]:https://travis-ci.org/go-kafka/connect.svg?branch=master
 [build status]: https://travis-ci.org/go-kafka/connect
 [coverage-badge]: https://codecov.io/gh/go-kafka/connect/branch/master/graph/badge.svg

client.go

@@ -20,7 +20,7 @@ const (
 	// DefaultHostURL is the default HTTP host used for connecting to a Kafka
 	// Connect REST API.
 	DefaultHostURL = "http://localhost:8083/"
-	userAgent      = "go-kafka/0.9 connect/" + VERSION
+	userAgent      = "go-kafka/0.9 connect/" + Version
 )
 
 // A Client manages communication with the Kafka Connect REST API.

cmd/kafka-connect/kafka-connect.go

@@ -13,7 +13,14 @@ import (
 	"github.com/go-kafka/connect"
 )
 
-const hostenv = "KAFKA_CONNECT_CLI_HOST"
+const (
+	// Version is the kafka-connect CLI version.
+	Version       = "0.9.0"
+	versionString = "kafka-connect version " + Version + "\n" +
+		"go-kafka/connect version " + connect.Version
+
+	hostenv = "KAFKA_CONNECT_CLI_HOST"
+)
 
 // ValidationError indicates that command arguments break an expected invariant.
 type ValidationError struct {
@@ -42,6 +49,7 @@ var (
 	listCmd, createCmd, updateCmd, deleteCmd *kingpin.CmdClause
 	showCmd, configCmd, tasksCmd, statusCmd  *kingpin.CmdClause
 	pauseCmd, resumeCmd, restartCmd          *kingpin.CmdClause
+	versionCmd                               *kingpin.CmdClause
 
 	newConnectorFilePath, connectorConfigPath string
 )
@@ -53,7 +61,7 @@ func init() {
 // BuildApp constructs the kafka-connect command line interface.
 func BuildApp() *kingpin.Application {
 	app := kingpin.New("kafka-connect", "Command line utility for managing Kafka Connect.").
-		Version("kafka-connect CLI " + connect.VERSION).
+		Version(Version). // man page template messed up by versionString...
 		Author("Ches Martin").
 		UsageWriter(os.Stdout)
 
@@ -78,6 +86,7 @@ func BuildApp() *kingpin.Application {
 	pauseCmd = app.Command("pause", "Pause a connector and its tasks.")
 	resumeCmd = app.Command("resume", "Resume a paused connector.")
 	restartCmd = app.Command("restart", "Restart a connector and its tasks.")
+	versionCmd = app.Command("version", "Shows kafka-connect version information.")
 
 	// TODO: New stuff
 	// plugin subcommand: list (default), validate
@@ -246,6 +255,10 @@ func run(subcommand string) error {
 		// TODO: verify error output of 409 Conflict
 		return affectConnector(connName, client.RestartConnector, "Restarted")
 
+	case versionCmd.FullCommand():
+		_, err := fmt.Println(versionString)
+		return err
+
 	default: // won't reach here, arg parsing handles unknown commands
 		return fmt.Errorf("Command `%v` is missing implementation!", subcommand)
 	}

connectors.go

@@ -149,8 +149,7 @@ func (c *Client) UpdateConnectorConfig(name string, config ConnectorConfig) (*Co
 }
 
 // DeleteConnector deletes a connector with the given name, halting all tasks
-// and deleting its configuration. Returns whether deletion was successful or
-// not.
+// and deleting its configuration.
 //
 // See: http://docs.confluent.io/current/connect/userguide.html#delete--connectors-(string-name)-
 func (c *Client) DeleteConnector(name string) (*http.Response, error) {

version.go

@@ -1,6 +1,5 @@
-// Package connect provides TODO
+// Package connect provides a client for the Kafka Connect REST API.
 package connect
 
-// VERSION is a programmatically-available declaration of the kafka-connect
-// library version.
-const VERSION = "0.1.0"
+// Version is the go-kafka/connect library version.
+const Version = "0.9.0"