openstack/governance
Code Issues Proposed changes

guidelines for managing releases of binary artifacts

Browse Source 
Change-Id: Ib1dc839773e2b95e017456c2d0082258ddc6cdd6
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
This commit is contained in:
Doug Hellmann 2017-05-30 15:20:27 -04:00 committed by Davanum Srinivas (dims)
parent a0a7ede72b
commit 6bc8e67df5
1 changed files with 118 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
resolutions/20170530-binary-artifacts.rst Normal file
View File

@ -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
<http://www.apache.org/licenses/LICENSE-2.0.html>`__, 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?"
<http://lists.openstack.org/pipermail/openstack-dev/2017-May/116677.html>`__
* There were at least 2 sessions at the Forum in Boston in 2017 to
cover `"Methods and Projects for deploying OpenStack with
Containers"
<https://etherpad.openstack.org/p/boston-deploying-openstack-on-k8s>`__
during which the topic was discussed.