diff --git a/resolutions/20170530-binary-artifacts.rst b/resolutions/20170530-binary-artifacts.rst new file mode 100644 index 000000000..34d28f827 --- /dev/null +++ b/resolutions/20170530-binary-artifacts.rst @@ -0,0 +1,118 @@ +================================================================= + 2017-05-30 Guidelines for Managing Releases of Binary Artifacts +================================================================= + +Until recently, the community has avoided releasing "binary" artifacts +such as compiled executables, operating system packages, or system +images. We have cited several reasons for the existing policy: + +1. Binary executables, especially for languages that statically link, + vendor, or aggregate dependencies, are harder to update if the code + is subject to logical or security-related bugs. +2. System packages built in the community are not likely to be + supported by the system vendors. +3. System and container images contain many different pieces of + software, and therefore have an even greater risk of including + faulty or malicious content. + +Because the community did not have the resources to support the +inevitable use of binary artifacts in production deployments, we +focused on distributing OpenStack in source form by publishing source +archives to tarballs.openstack.org. We have also published +developer-focused Python package formats such as sdists and wheels to +pypi.python.org because those formats are useful in our own CI +systems, and because it seemed clear, if only implicitly, that +consumers of the packages would understand they are not supported for +production use. + +In contrast, the open source communities based around some of the +tools that we are adopting do release binary artifacts as a standard +practice. Container images and full system images are often published +to community-specific indexing services such as Docker Hub or +Vagrant's Atlas service. The results can then be consumed by anyone +familiar with the tools for searching those repositories. Binary +executables built from compiled languages such as Go are often made +available from project websites, as well. + +Guidelines +========== + +Although our community still does not have resources to support +production deployments, this shift in the common practices of other +communities is leading some of our teams to want to distribute binary +artifacts as well. This resolution describes some guidelines for doing +so, while mitigating the risks associated with someone inevitably +using the results in production. + +* Users need to know what they are getting when they download + artifacts, to enable them to know which artifacts are compatible + with each other, with their infrastructure and to be able to find appropriate + documentation. For this reason, the metadata for each artifact must + clearly specify the name and version of the principal component it + contains as well as the architecture for which it is built. + For example, if an image contains the nova conductor from + version 16.0.0, that information should be accessible, either + through the name or through metadata associated with the image using + whatever mechanism is common to the index or repository service + where the image is published. + +* Consumers of these artifacts need to be able to track bugs and + security issues in components included in the artifacts. For this + reason, all published binary artifacts must be accompanied by a + manifest describing the versions of all components used to build it, + whether they be the libraries used to build an executable or the + system packages included in an image. + +* The contents of binary artifacts "age" and become out of date as + development work continues, either on the primary component or on + dependencies built into the artifact. Consumers of these artifacts + need to know whether they have a recent version, or if they are far + out of date. For this reason, all binary artifacts should include + metadata containing the date they were built, as well as the date + they were published (if it is different). + +* Users need to be able to reproduce environments, and developers need + to be able to reproduce builds in order to investigate issues. + Contributors to projects should not be expected to support or debug + arbitrary versions packaged by someone else. For these reasons, + binary artifacts published to third-party registries should only be + built from well-defined points in the history of an OpenStack + project, identified with signed tags on the git repository. The inputs + to recreate the build, including configuration files and build scripts, + must be made available so that anyone can rebuild the image. + +* We do not want the artifacts to be seen as owned by the community at + large, if only a few people can actually address issues. For this + reason, the metadata for binary artifacts must not say or imply that + they are produced by "the OpenStack community." Specific team names + should be used instead. + +* Because only a subset of the community is producing and maintaining + the artifacts, we need to ensure it is clear to consumers where to + go if they do want help. For this reason, each artifact must be + published with metadata, such as a bug tracker URL, describing where + and how to seek help. + +* Consumers of these artifacts need to understand the limits of the + support they are likely to be able to receive. All of our official + projects are released under the `Apache License + `__, which includes + a *Disclaimer of Warranty* stating that the software is provided + without warranty and a *Limitation of Liability* saying that + contributors are not liable for damages. It also, however, includes + a clause allowing "redistributors" to offer additional levels of + support. Teams must not indicate that they are offering support for + any binary artifacts in a way that implies the warranty or liability + for that support extends to the rest of the community. + +References +========== + +* This was discussed extensively in the openstack-dev mailing list + thread `"do we want to be publishing binary container images?" + `__ +* There were at least 2 sessions at the Forum in Boston in 2017 to + cover `"Methods and Projects for deploying OpenStack with + Containers" + `__ + during which the topic was discussed.