Merge pull request #1708 from endocode/dongsu/docs-release-howto

docs: add a release instruction document

Documentation/api-v1.md

@@ -209,7 +209,7 @@ Add, change, or remove metadata from one or more machines.
 #### Request
 
 ```
-PATCH /machines HTTP/1.1
+PATCH /fleet/v1/machines HTTP/1.1
 
 [
   { "op": "add", "path": "/<machine_id>/metadata/<name>", "value": <new value> },

Documentation/release.md

@@ -0,0 +1,67 @@
+# fleet release guide
+
+The guide talks about how to release a new version of fleet.
+
+The procedure includes some manual steps for sanity checking but it can probably be further scripted. Please keep this document up-to-date if you want to make changes to the release process.
+
+## Prepare Release
+
+Set desired version as environment variable for following steps. Here is an example to release 0.13.0:
+
+```
+export VERSION=v0.13.0
+```
+
+All releases version numbers follow the format of [semantic versioning 2.0.0](http://semver.org/).
+
+### Major, Minor Version Release, or its Pre-release
+
+- Ensure the relevant milestone on GitHub is complete. All referenced issues should be closed, or moved elsewhere.
+- Ensure the latest upgrade documentation is available.
+- Add feature capability maps for the new version, if necessary.
+
+## Write Release Note
+
+- Write introduction for the new release. For example, what major bug we fix, what new features we introduce or what performance improvement we make.
+- Write changelog for the last release. The changelog should be straightforward and easy to understand for the end-user.
+
+## Tag Version
+
+- Ensure all tests on CI system are passed.
+- Manually check fleet is buildable in Linux, Darwin.
+- Manually check upgrade fleet cluster of previous minor version works well.
+- Manually check new features work well.
+- Add an annotated tag through `git tag -a ${VERSION}`.
+- Sanity check tag correctness through `git show tags/$VERSION`.
+- Push the tag to GitHub through `git push origin tags/$VERSION`. This assumes `origin` corresponds to "https://github.com/coreos/fleet".
+
+## Build Release Binaries and Images
+
+- Ensure `acbuild` is available.
+- Ensure `docker` is available.
+
+Run release script in root directory:
+
+```
+./scripts/release.sh ${VERSION}
+```
+
+It generates all release binaries and images under directory `./release`.
+
+## Publish Release Page in GitHub
+
+- Set release title as the version name.
+- Follow the format of previous release pages.
+- Attach the generated binaries and aci image.
+- Publish the release!
+
+## Publish Docker Image in Quay.io
+
+- Push docker image:
+
+```
+docker login quay.io
+docker push quay.io/coreos/fleet:${VERSION}
+```
+
+- Add `latest` tag to the new image on [quay.io](https://quay.io/repository/coreos/fleet?tag=latest&tab=tags) if this is a stable release.

Documentation/rkt_guide.md

@@ -14,11 +14,15 @@ Then you can run fleet under rkt:
 
 ```
 # rkt --insecure-options=image run --inherit-env \
+  --volume etc-fleet,kind=host,source=/etc/fleet \
   --volume machine-id,kind=host,source=/etc/machine-id \
   --volume dbus-socket,kind=host,source=/run/dbus/system_bus_socket \
   --volume fleet-units,kind=host,source=/run/fleet/units \
-  --volume etc-fleet,kind=host,source=/etc/fleet \
-  fleetd-0.9.0.aci
+  --mount volume=etc-fleet,target=/etc/fleet \
+  --mount volume=machine-id,target=/etc/machine-id \
+  --mount volume=dbus-socket,target=/run/dbus/system_bus_socket \
+  --mount volume=fleet-units,target=/run/fleet/units \
+  fleetd-0.13.0.aci
 ```
 
 You can configure it modifying the file `/etc/fleet/fleet.conf` in your host and with enviroment variables as described in [deployment-and-configuration.md][deployment-and-configuration].
@@ -37,7 +41,7 @@ After=fleet.socket
 
 [Service]
 ExecStartPre=/usr/bin/mkdir -p /run/fleet/units
-ExecStart=/usr/bin/rkt --insecure-options=image run --inherit-env --volume machine-id,kind=host,source=/etc/machine-id --volume dbus-socket,kind=host,source=/run/dbus/system_bus_socket --volume fleet-units,kind=host,source=/run/fleet/units --volume etc-fleet,kind=host,source=/etc/fleet /usr/images/fleetd-0.9.0.aci
+ExecStart=/usr/bin/rkt --insecure-options=image run --inherit-env --volume etc-fleet,kind=host,source=/etc/fleet --volume machine-id,kind=host,source=/etc/machine-id --volume dbus-socket,kind=host,source=/run/dbus/system_bus_socket --volume fleet-units,kind=host,source=/run/fleet/units --mount volume=etc-fleet,target=/etc/fleet --mount volume=machine-id,target=/etc/machine-id --mount volume=dbus-socket,target=/run/dbus/system_bus_socket --mount volume=fleet-units,target=/run/fleet/units /usr/images/fleetd-0.13.0.aci
 Restart=always
 RestartSec=10s
 ```