Skip to content

Commit 3855502

Browse files
fnoblefnoble
committed
Merge pull request #102 from mookerji/how-to-release
Release HOWTO and supporting Makefile tasks.
2 parents 16f8ef8 + fffeba0 commit 3855502

File tree

2 files changed

+144
-2
lines changed

2 files changed

+144
-2
lines changed

‎HOWTO.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
libsbp Development Procedures
2+
=============================
3+
4+
This document summarizes some practices around contributions to this
5+
library. These instructions don't come with a warranty yet, so please
6+
feel free to update it to mirror reality.
7+
8+
# Adding and Testing New Messages
9+
10+
Adding new SBP messages is currently a very organic, social
11+
process. This is likely to change in the future.
12+
13+
0. Read, understand, and imitate the current SBP definition syntax by
14+
looking at the annotated [`example`](spec/example/yaml) and
15+
[`existing`](spec/yaml/swiftnav/sbp) messages.
16+
17+
1. Add a message definition to the approprate package, or create a new
18+
one if needed. Read the **Message Guidelines** below.
19+
20+
2. Generate new clients and documentation by running `make
21+
all`. Verify that the generated code, which isn't too complicated,
22+
meets your expectations, as allowed messages are limited by the
23+
underlying language implementation. For example, you can't specify
24+
a message that has a variable-length array in the middle of the
25+
message, since the generated SBP structs for the C client will
26+
materialize a 0-length array C99 extension in the middle of the
27+
struct. GCC won't compile this.
28+
29+
3. Add a [`test`](spec/tests/yaml/swiftnav/sbp) case and update the
30+
appropriate language libaries. Run `make test`.
31+
32+
4. Submit a pull request.
33+
34+
5. If Swift's internal test tooling needs to be updated to use your
35+
new message, deploy the updated Python client first, and then the C
36+
client. We haven't quite decided on the details of this process.
37+
38+
# Message Guidelines
39+
40+
Some thoughts to consider when adding a new message:
41+
42+
- Messages should be as simple as possible but no simpler.
43+
44+
- *Build for the future*. Once a message is promoted to "stable" its
45+
general structure must never change. You should think very hard
46+
about what kinds of fields you may wish you had included in the
47+
future. Consider adding some extra reserved bits for future
48+
expansion (within reason).
49+
50+
- *Size matters*. SBP is designed to be a lightweight protocol used by
51+
small, embedded devices. Consider using fixed point representations
52+
where possible, and don't specify excessive precision or
53+
range. Avoid non-byte aligned types though, they are a pain to
54+
decode.
55+
56+
- *Generalize*. SBP is a protocol that exists separately from any
57+
specific device that uses SBP (e.g. Piksi). It should be with a very
58+
heavy heart that you include anything device specific in the
59+
protocol, and even then it should only be added to a device specific
60+
package.
61+
62+
- *Draft message changes*. There are different ways to change draft
63+
messages, which are allowed to be in flux. Doing so isn't free of
64+
consequences, particularly if that message is used by others during
65+
internal development. Changing a message name, its ID, or its field
66+
contents is fine, as long as the migrating consumers is a
67+
well-understood process.
68+
69+
# Releasing New Versions of the Library
70+
71+
Oh boy, so you've decided to release a new version of libsbp.
72+
73+
0. Branch and tag a new release. Tag the release version:
74+
75+
```shell
76+
# Produces most recent tag (e.g., v0.29)
77+
git describe --abbrev=0 --tags
78+
# Increment that value, create a new one (e.g, v0.30), and push
79+
git tag -a INCREMENTED_TAG
80+
git push upstream INCREMENTED_TAG
81+
```
82+
83+
1. Verify that package dependencies, their version numbers, and the
84+
libsbp version number in the C, Python, and LaTeX developer
85+
documentation are consistent.
86+
87+
2. Add to RELEASE_NOTES.md and update the CHANGELOG details with `make
88+
release`. Submit a pull request. This requires
89+
[github-changelog-generator](https://github.com/skywinder/github-changelog-generator),
90+
and a CHANGELOG_GITHUB_TOKEN in your PATH if you don't already have
91+
them.
92+
93+
3. Create a release on
94+
[GitHub](https://github.com/swift-nav/libsbp/releases) and add the
95+
RELEASE_NOTES.md.
96+
97+
4. Distribute release packages: `make dist`. You may need credentials
98+
on the appropriate package repositories.
99+
100+
5. Announce release to the
101+
[forum](https://groups.google.com/forum/#!forum/swiftnav-discuss).
102+
103+
6. Releases are not only never perfect, they never really end. Please
104+
pay special attention to any downstream projects or users that may
105+
have issues or regressions as a consequence of the release version.
106+
107+
# Contributions
108+
109+
This library is developed internally by Swift Navigation. We welcome
110+
Github issues and pull requests, as well as discussions of potential
111+
problems and enhancement suggestions on the
112+
[forum](https://groups.google.com/forum/#!forum/swiftnav-discuss).

‎Makefile‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,38 @@
11
# Convenience Makefile for generating and releasing SBP client
2-
# libraries.
2+
# libraries. Please read and understand the contents of this file
3+
# before using it to do Crazy Things.
34

45
SWIFTNAV_ROOT := $(shell pwd)
56
MAKEFLAGS += SWIFTNAV_ROOT=$(SWIFTNAV_ROOT)
67
SBP_SPEC_DIR := $(SWIFTNAV_ROOT)/spec/yaml/swiftnav/sbp/
78
SBP_GEN_BIN := python sbpg/generator.py
9+
CHANGELOG_GITHUB_TOKEN := CHANGELOG_GITHUB_TOKEN
810

9-
.PHONY: help all c python docs pdf html test
11+
.PHONY: help all c python docs pdf html test release dist
1012

1113
help:
1214
@echo
1315
@echo "Helper for generating and releasing SBP client libraries."
1416
@echo
17+
@echo "(Please read before using!)"
18+
@echo
1519
@echo "Please use \`make <target>' where <target> is one of"
1620
@echo " help to display this help message"
1721
@echo " all to make SBP clients across all languages"
1822
@echo " c to make C headers"
23+
@echo " dist to distribute packages"
1924
@echo " docs to make HTML and pdf documentation"
2025
@echo " html to make all HTML language docs"
2126
@echo " pdf to make SBP LaTeX datasheet"
2227
@echo " python to make Python bindings"
28+
@echo " release to handle some release tasks"
2329
@echo " test to run all tests"
2430
@echo
2531

2632
all: c python test docs
2733

2834
c:
35+
@echo
2936
@echo "Generating C headers..."
3037
@echo
3138
cd $(SWIFTNAV_ROOT)/generator; \
@@ -37,6 +44,7 @@ c:
3744
@echo "Finished. Please check $(SWIFTNAV_ROOT)/c/include/libsbp."
3845

3946
python:
47+
@echo
4048
@echo "Generating Python bindings..."
4149
@echo
4250
cd $(SWIFTNAV_ROOT)/generator; \
@@ -47,11 +55,22 @@ python:
4755
@echo
4856
@echo "Finished! Please check $(SWIFTNAV_ROOT)/python/sbp."
4957

58+
dist:
59+
@echo
60+
@echo "Deploy packages ..."
61+
@echo
62+
cd $(SWIFTNAV_ROOT)/python; \
63+
python setup.py sdist upload -r pypi; \
64+
cd $(SWIFTNAV_ROOT);
65+
@echo
66+
@echo "Finished! Please check $(SWIFTNAV_ROOT)/python/sbp."
67+
5068
docs: pdf html
5169

5270
pdf:
5371
@echo
5472
@echo "Generating datasheet documentation..."
73+
@echo
5574
cd $(SWIFTNAV_ROOT)/generator; \
5675
$(SBP_GEN_BIN) -i $(SBP_SPEC_DIR) \
5776
-o $(SWIFTNAV_ROOT)/latex/ \
@@ -96,3 +115,14 @@ test:
96115
cd $(SWIFTNAV_ROOT);
97116
@echo
98117
@echo "Finished!"
118+
119+
release:
120+
@echo
121+
@echo "Run release boilerplate..."
122+
@echo
123+
github_changelog_generator --no-author \
124+
-t $(CHANGELOG_GITHUB_TOKEN)$ \
125+
-o DRAFT_CHANGELOG.md \
126+
swift-nav/libsbp
127+
@echo
128+
@echo "Added CHANGELOG details to DRAFT_CHANGELOG.md!"

0 commit comments

Comments
 (0)