Release HOWTO and supporting Makefile tasks.

HOWTO.md

@@ -0,0 +1,112 @@
+libsbp Development Procedures
+=============================
+
+This document summarizes some practices around contributions to this
+library. These instructions don't come with a warranty yet, so please
+feel free to update it to mirror reality.
+
+# Adding and Testing New Messages
+
+Adding new SBP messages is currently a very organic, social
+process. This is likely to change in the future.
+
+0. Read, understand, and imitate the current SBP definition syntax by
+   looking at the annotated [`example`](spec/example/yaml) and
+   [`existing`](spec/yaml/swiftnav/sbp) messages.
+
+1. Add a message definition to the approprate package, or create a new
+   one if needed. Read the **Message Guidelines** below.
+
+2. Generate new clients and documentation by running `make
+   all`. Verify that the generated code, which isn't too complicated,
+   meets your expectations, as allowed messages are limited by the
+   underlying language implementation. For example, you can't specify
+   a message that has a variable-length array in the middle of the
+   message, since the generated SBP structs for the C client will
+   materialize a 0-length array C99 extension in the middle of the
+   struct. GCC won't compile this.
+
+3. Add a [`test`](spec/tests/yaml/swiftnav/sbp) case and update the
+   appropriate language libaries. Run `make test`.
+
+4. Submit a pull request.
+
+5. If Swift's internal test tooling needs to be updated to use your
+   new message, deploy the updated Python client first, and then the C
+   client. We haven't quite decided on the details of this process.
+
+# Message Guidelines
+
+Some thoughts to consider when adding a new message:
+
+- Messages should be as simple as possible but no simpler.
+
+- *Build for the future*. Once a message is promoted to "stable" its
+  general structure must never change. You should think very hard
+  about what kinds of fields you may wish you had included in the
+  future. Consider adding some extra reserved bits for future
+  expansion (within reason).
+
+- *Size matters*. SBP is designed to be a lightweight protocol used by
+  small, embedded devices. Consider using fixed point representations
+  where possible, and don't specify excessive precision or
+  range. Avoid non-byte aligned types though, they are a pain to
+  decode.
+
+- *Generalize*. SBP is a protocol that exists separately from any
+  specific device that uses SBP (e.g. Piksi). It should be with a very
+  heavy heart that you include anything device specific in the
+  protocol, and even then it should only be added to a device specific
+  package.
+
+- *Draft message changes*. There are different ways to change draft
+  messages, which are allowed to be in flux. Doing so isn't free of
+  consequences, particularly if that message is used by others during
+  internal development. Changing a message name, its ID, or its field
+  contents is fine, as long as the migrating consumers is a
+  well-understood process.
+
+# Releasing New Versions of the Library
+
+Oh boy, so you've decided to release a new version of libsbp.
+
+0. Branch and tag a new release. Tag the release version:
+
+    ```shell
+    # Produces most recent tag (e.g., v0.29)
+    git describe --abbrev=0 --tags
+    # Increment that value, create a new one (e.g, v0.30), and push
+    git tag -a INCREMENTED_TAG
+    git push upstream INCREMENTED_TAG
+    ```
+
+1. Verify that package dependencies, their version numbers, and the
+   libsbp version number in the C, Python, and LaTeX developer
+   documentation are consistent.
+
+2. Add to RELEASE_NOTES.md and update the CHANGELOG details with `make
+   release`. Submit a pull request. This requires
+   [github-changelog-generator](https://github.com/skywinder/github-changelog-generator),
+   and a CHANGELOG_GITHUB_TOKEN in your PATH if you don't already have
+   them.
+
+3. Create a release on
+   [GitHub](https://github.com/swift-nav/libsbp/releases) and add the
+   RELEASE_NOTES.md.
+
+4. Distribute release packages: `make dist`. You may need credentials
+   on the appropriate package repositories.
+
+5. Announce release to the
+   [forum](https://groups.google.com/forum/#!forum/swiftnav-discuss).
+
+6. Releases are not only never perfect, they never really end. Please
+   pay special attention to any downstream projects or users that may
+   have issues or regressions as a consequence of the release version.
+
+# Contributions
+
+This library is developed internally by Swift Navigation. We welcome
+Github issues and pull requests, as well as discussions of potential
+problems and enhancement suggestions on the
+[forum](https://groups.google.com/forum/#!forum/swiftnav-discuss).

Makefile

@@ -1,31 +1,38 @@
 # Convenience Makefile for generating and releasing SBP client
-# libraries.
+# libraries. Please read and understand the contents of this file
+# before using it to do Crazy Things.
 
 SWIFTNAV_ROOT := $(shell pwd)
 MAKEFLAGS += SWIFTNAV_ROOT=$(SWIFTNAV_ROOT)
 SBP_SPEC_DIR := $(SWIFTNAV_ROOT)/spec/yaml/swiftnav/sbp/
 SBP_GEN_BIN := python sbpg/generator.py
+CHANGELOG_GITHUB_TOKEN := CHANGELOG_GITHUB_TOKEN
 
-.PHONY: help all c python docs pdf html test
+.PHONY: help all c python docs pdf html test release dist
 
 help:
 	@echo
 	@echo "Helper for generating and releasing SBP client libraries."
 	@echo
+	@echo "(Please read before using!)"
+	@echo
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  help      to display this help message"
 	@echo "  all       to make SBP clients across all languages"
 	@echo "  c         to make C headers"
+	@echo "  dist      to distribute packages"
 	@echo "  docs      to make HTML and pdf documentation"
 	@echo "  html      to make all HTML language docs"
 	@echo "  pdf       to make SBP LaTeX datasheet"
 	@echo "  python    to make Python bindings"
+	@echo "  release   to handle some release tasks"
 	@echo "  test      to run all tests"
 	@echo
 
 all: c python test docs
 
 c:
+	@echo
 	@echo "Generating C headers..."
 	@echo
 	cd $(SWIFTNAV_ROOT)/generator; \
@@ -37,6 +44,7 @@ c:
 	@echo "Finished. Please check $(SWIFTNAV_ROOT)/c/include/libsbp."
 
 python:
+	@echo
 	@echo "Generating Python bindings..."
 	@echo
 	cd $(SWIFTNAV_ROOT)/generator; \
@@ -47,11 +55,22 @@ python:
 	@echo
 	@echo "Finished! Please check $(SWIFTNAV_ROOT)/python/sbp."
 
+dist:
+	@echo
+	@echo "Deploy packages ..."
+	@echo
+	cd $(SWIFTNAV_ROOT)/python; \
+	python setup.py sdist upload -r pypi; \
+	cd $(SWIFTNAV_ROOT);
+	@echo
+	@echo "Finished! Please check $(SWIFTNAV_ROOT)/python/sbp."
+
 docs: pdf html
 
 pdf:
 	@echo
 	@echo "Generating datasheet documentation..."
+	@echo
 	cd $(SWIFTNAV_ROOT)/generator; \
 	$(SBP_GEN_BIN) -i $(SBP_SPEC_DIR) \
 		       -o $(SWIFTNAV_ROOT)/latex/ \
@@ -96,3 +115,14 @@ test:
 	cd $(SWIFTNAV_ROOT);
 	@echo
 	@echo "Finished!"
+
+release:
+	@echo
+	@echo "Run release boilerplate..."
+	@echo
+	github_changelog_generator --no-author \
+				   -t $(CHANGELOG_GITHUB_TOKEN)$ \
+				   -o DRAFT_CHANGELOG.md \
+				   swift-nav/libsbp
+	@echo
+	@echo "Added CHANGELOG details to DRAFT_CHANGELOG.md!"