498 lines
24 KiB
XML
498 lines
24 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE chapter [
|
||
<!-- Some useful entities borrowed from HTML -->
|
||
<!ENTITY ndash "–">
|
||
<!ENTITY mdash "—">
|
||
<!ENTITY hellip "…">
|
||
<!ENTITY plusmn "±">
|
||
]>
|
||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||
xml:id="upstream_openstack">
|
||
<?dbhtml stop-chunking?>
|
||
<title>Upstream OpenStack</title>
|
||
<para>OpenStack is founded on a thriving community which is a
|
||
source of help, and welcomes your contributions. This section
|
||
details some of the ways you can interact with the others
|
||
involved.</para>
|
||
|
||
<section xml:id="get_help">
|
||
<title>Getting Help</title>
|
||
<para>There are several avenues available for seeking
|
||
assistance. The quickest way to is to help the community
|
||
help you. Search the Q&A sites, mailing list archives,
|
||
and bug lists for issues similar to yours. If you can't
|
||
find anything, follow the directions for Reporting Bugs in
|
||
the section below or use one of the channels for support
|
||
below.</para>
|
||
<para>Your first port of call should be the official OpenStack
|
||
documentation, found on http://docs.openstack.org.</para>
|
||
<para>You can get questions answered on the ask.openstack.org site.</para>
|
||
<para>
|
||
<link
|
||
xlink:href="https://wiki.openstack.org/wiki/Mailing_Lists"
|
||
>Mailing
|
||
Lists</link> (https://wiki.openstack.org/wiki/Mailing_Lists)
|
||
are also a great place to get help. The wiki page has more
|
||
information about the various lists. As an operator, the
|
||
main lists you should be aware of are:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<link
|
||
xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack"
|
||
>General
|
||
list</link>: <code>openstack@lists.openstack.org</code>.
|
||
The scope of this list is the current state of
|
||
OpenStack. This is a very high traffic mailing
|
||
list, with many, many emails per day.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<link
|
||
xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators"
|
||
>Operators
|
||
list</link>: <code>openstack-operators@lists.openstack.org.</code>
|
||
This list is intended for discussion among
|
||
existing OpenStack cloud operators, such as
|
||
yourself. Currently, this list is relatively low
|
||
traffic, on the order of one email a day.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<link
|
||
xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev"
|
||
>Development
|
||
list</link>: <code>openstack-dev@lists.openstack.org</code>.
|
||
The scope of this list is the future state of
|
||
OpenStack. This is a high traffic mailing list,
|
||
with multiple emails per day.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>We recommend you subscribe to the general list and the
|
||
operator list, although you must set up filters to
|
||
manage the volume for the general list. You'll also find
|
||
links to the mailing list archives on the mailing list
|
||
wiki page where you can search through the
|
||
discussions.</para>
|
||
<para>
|
||
<link
|
||
xlink:href="https://wiki.openstack.org/wiki/IRC"
|
||
>Multiple IRC
|
||
channels</link> (https://wiki.openstack.org/wiki/IRC) are
|
||
available for general questions and developer discussions.
|
||
The general discussion channel is <code>#openstack</code>
|
||
on <code>irc.freenode.net</code>.</para>
|
||
</section>
|
||
<section xml:id="report_bugs">
|
||
<title>Reporting Bugs</title>
|
||
<para>As an operator, you are in a very good position to
|
||
report unexpected behavior with your cloud. As OpenStack
|
||
is flexible, you may be the only individual to report a
|
||
particular issue. Every issue is important to fix so it is
|
||
essential to learn how to easily submit a bug
|
||
report.</para>
|
||
<para>All OpenStack projects use <link
|
||
xlink:href="http://launchpad.net/"
|
||
>Launchpad</link> for bug tracking. You'll need to create
|
||
an account on Launchpad before you can submit a bug
|
||
report.</para>
|
||
<para>Once you have a Launchpad account, reporting a bug is as
|
||
simple as identifying the project, or projects that are
|
||
causing the issue. Sometimes this is more difficult than
|
||
expected, but those working on the bug triage are happy to
|
||
help relocate issues if their not in the right place
|
||
initially.</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/nova/+filebug"
|
||
>Nova</link> (https://bugs.launchpad.net/nova/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/python-novaclient/+filebug"
|
||
>python-novaclient</link> (https://bugs.launchpad.net/python-novaclient/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/swift/+filebug"
|
||
>Swift</link> (https://bugs.launchpad.net/swift/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/python-swiftclient/+filebug"
|
||
>python-swiftclient</link>
|
||
(https://bugs.launchpad.net/python-swiftclient/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/glance/+filebug"
|
||
>Glance</link> (https://bugs.launchpad.net/glance/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/python-glanceclient/+filebug"
|
||
>python-glanceclient</link>
|
||
(https://bugs.launchpad.net/python-glanceclient/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/keystone/+filebug"
|
||
>Keystone</link> (https://bugs.launchpad.net/keystone/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/python-keystoneclient/+filebug"
|
||
>python-keystoneclient</link>
|
||
(https://bugs.launchpad.net/python-keystoneclient/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/neutron/+filebug"
|
||
>Neutron</link> (https://bugs.launchpad.net/neutron/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/python-neutronclient/+filebug"
|
||
>python-neutronclient</link>
|
||
(https://bugs.launchpad.net/python-neutronclient/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/cinder/+filebug"
|
||
>Cinder</link> (https://bugs.launchpad.net/cinder/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/python-cinderclient/+filebug"
|
||
>python-cinderclient</link>
|
||
(https://bugs.launchpad.net/python-cinderclient/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug in <link
|
||
xlink:href="https://bugs.launchpad.net/horizon/+filebug"
|
||
>Horizon</link> (https://bugs.launchpad.net/horizon/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug with the <link
|
||
xlink:href="http://bugs.launchpad.net/openstack-manuals/+filebug"
|
||
>documentation</link> (http://bugs.launchpad.net/openstack-manuals/+filebug)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Report a bug with the <link
|
||
xlink:href="http://bugs.launchpad.net/openstack-api-site/+filebug"
|
||
>API
|
||
documentation</link> (http://bugs.launchpad.net/openstack-api-site/+filebug)</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>To write a good bug report, the following process is
|
||
essential. First, search for the bug to make sure there is
|
||
no bug already filed for the same issue. If you find one,
|
||
be sure to click on "This bug affects X people. Does this
|
||
bug affect you?" If you can't find the issue then enter
|
||
the details of your report. It should at least
|
||
include:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>The release, or milestone, or commit ID
|
||
corresponding to the software that you are
|
||
running.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>The operating system and version where you've
|
||
identified the bug.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Steps to reproduce the bug, including what went
|
||
wrong.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Description of the expected results instead of
|
||
what you saw.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Read and understood your log files so you only
|
||
include relevant excerpts.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>When you do this, the bug is created with:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Status: <emphasis>New</emphasis>
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>In the bug comments, you can contribute instructions on
|
||
how to fix a given bug, and set it to
|
||
<emphasis>Triaged</emphasis>. Or you can directly fix
|
||
it: assign the bug to yourself, set it to <emphasis>In
|
||
progress</emphasis>, branch the code, implement the
|
||
fix, and propose your change for merging into trunk. But
|
||
let's not get ahead of ourselves, there are bug triaging
|
||
tasks as well.</para>
|
||
<section xml:id="confirm_priority">
|
||
<title>Confirming & Prioritizing</title>
|
||
<para>This stage is about checking that a bug is real and
|
||
assessing its impact. Some of these steps require bug
|
||
supervisor rights (usually limited to core teams). If
|
||
the bug lacks information to properly reproduce or
|
||
assess the importance of the bug, the bug is set
|
||
to:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Status: <emphasis>Incomplete</emphasis>
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>Once you have reproduced the issue (or are 100%
|
||
confident that this is indeed a valid bug) and have
|
||
permissions to do so, set:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Status: <emphasis>Confirmed</emphasis>
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>Core developers also prioritize the bug, based
|
||
on its impact:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Importance: <Bug impact></para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>The bug impacts are categorized as follows:</para>
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
<emphasis>Critical</emphasis> if the bug
|
||
prevents a key feature from working properly
|
||
(regression) for all users (or without a
|
||
simple workaround) or result in data
|
||
loss</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<emphasis>High</emphasis> if the bug prevents
|
||
a key feature from working properly for some
|
||
users (or with a workaround)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<emphasis>Medium</emphasis> if the bug
|
||
prevents a secondary feature from working
|
||
properly</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<emphasis>Low</emphasis> if the bug is mostly
|
||
cosmetic</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<emphasis>Wishlist</emphasis> if the bug is
|
||
not really a bug, but rather a welcome change
|
||
in behavior</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
<para>If the bug contains the solution, or a patch, set
|
||
the bug status to <emphasis>Triaged</emphasis>
|
||
</para>
|
||
</section>
|
||
<section xml:id="bug_fixing">
|
||
<title>Bug Fixing</title>
|
||
<para>At this stage, a developer works on a fix.
|
||
During that time, to avoid duplicating the
|
||
work, they should set:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Status: <emphasis>In progress</emphasis>
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Assignee: <yourself></para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>When the fix is ready, they propose and get the change reviewed.</para>
|
||
</section>
|
||
<section xml:id="after_change_is_accepted">
|
||
<title>After the Change is Accepted</title>
|
||
<para>After the change is reviewed, accepted, and lands in master, it automatically moves
|
||
to:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Status: <emphasis>Fix committed</emphasis>
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>When the fix makes it into a milestone or release
|
||
branch, it automatically moves to:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Milestone: Milestone the bug was fixed
|
||
in</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Status: <emphasis>Fix released</emphasis>
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
</section>
|
||
<section xml:id="openstack_community">
|
||
<title>Join the OpenStack Community</title>
|
||
<para>Since you've made it this far in the book, you should
|
||
consider becoming an official individual member of the
|
||
community and <link
|
||
xlink:href="https://www.openstack.org/join/">Join The
|
||
OpenStack Foundation</link>
|
||
(https://www.openstack.org/join/). The OpenStack
|
||
Foundation is an independent body providing shared
|
||
resources to help achieve the OpenStack mission by
|
||
protecting, empowering, and promoting OpenStack software
|
||
and the community around it, including users, developers
|
||
and the entire ecosystem. We all share the responsibility
|
||
to make this community the best it can possibly be and
|
||
signing up to be a member is the first step to
|
||
participating. Like the software, individual membership
|
||
within the OpenStack Foundation is free and accessible to
|
||
anyone.</para>
|
||
</section>
|
||
<section xml:id="contribute_to_docs">
|
||
<title>How to Contribute to the Documentation</title>
|
||
<para>OpenStack documentation efforts encompass operator and
|
||
administrator docs, API docs, and user docs.</para>
|
||
<para>The genesis of this book was an in-person event, but now
|
||
that the book is in your hands we want you to contribute
|
||
to it. OpenStack documentation follows the coding
|
||
principles of iterative work, with bug logging,
|
||
investigating, and fixing.</para>
|
||
<para>Just like the code, the <link
|
||
|
||
xlink:href="http://docs.openstack.org"
|
||
>docs.openstack.org</link> site is updated constantly
|
||
using the Gerrit review system, with source stored in
|
||
GitHub in the <link
|
||
xlink:href="http://github.com/openstack/openstack-manuals/"
|
||
>openstack-manuals</link> (http://github.com/openstack/openstack-manuals/)
|
||
repository and the <link
|
||
xlink:href="http://github.com/openstack/api-site/"
|
||
>api-site</link> (http://github.com/openstack/api-site/)
|
||
repository, in DocBook format.</para>
|
||
<para>To review the documentation before it's published, go to
|
||
the OpenStack Gerrit server at <link
|
||
|
||
xlink:href="http://review.openstack.org"
|
||
>review.openstack.org</link> and search for <link
|
||
|
||
xlink:href="https://review.openstack.org/#/q/status:open+project:openstack/openstack-manuals,n,z"
|
||
>project:openstack/openstack-manuals</link> or <link
|
||
|
||
xlink:href="https://review.openstack.org/#/q/status:open+project:openstack/api-site,n,z"
|
||
>project:openstack/api-site</link>.</para>
|
||
<para>See the <link
|
||
xlink:href="https://wiki.openstack.org/wiki/How_To_Contribute"
|
||
>How To
|
||
Contribute</link> (https://wiki.openstack.org/wiki/How_To_Contribute)
|
||
page on the wiki for more information on the steps you
|
||
need to take to submit your first documentation
|
||
review or change.</para>
|
||
</section>
|
||
<section xml:id="security_info">
|
||
<title>Security Information</title>
|
||
<para>As a community, we take security very seriously and
|
||
follow a specific process for reporting potential issues.
|
||
We vigilantly pursue fixes and regularly eliminate
|
||
exposures. You can report security issues you discover
|
||
through this specific process. The OpenStack Vulnerability
|
||
Management Team is a very small group of experts in
|
||
vulnerability management drawn from the OpenStack
|
||
community. Their job is facilitating the reporting of
|
||
vulnerabilities, coordinating security fixes and handling
|
||
progressive disclosure of the vulnerability information.
|
||
Specifically, the Team is responsible for the following
|
||
functions:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Vulnerability Management: All vulnerabilities
|
||
discovered by community members (or users) can be
|
||
reported to the Team.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Vulnerability Tracking: The Team will
|
||
curate a set of vulnerability related issues in
|
||
the issue tracker. Some of these issues are
|
||
private to the Team and the affected product
|
||
leads, but once remediation is in place, all
|
||
vulnerabilities are public.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Responsible Disclosure: As part of our
|
||
commitment to work with the security community,
|
||
the team ensures that proper credit is given
|
||
to security researchers who responsibly report
|
||
issues in OpenStack.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>We provide two ways to report issues to the OpenStack
|
||
Vulnerability Management Team depending on how sensitive
|
||
the issue is:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Open a bug in Launchpad and mark it as a
|
||
'security bug'. This makes the bug private and
|
||
accessible to only the Vulnerability Management
|
||
Team.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>If the issue is extremely sensitive, send
|
||
an encrypted email to one of the Team's
|
||
members. Find their GPG keys at <link
|
||
|
||
xlink:href="http://www.openstack.org/projects/openstack-security/"
|
||
>OpenStack Security</link>
|
||
(http://www.openstack.org/projects/openstack-security/).</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>You can find the full list of security-oriented teams
|
||
you can join at <link
|
||
xlink:href="https://wiki.openstack.org/wiki/SecurityTeams"
|
||
>Security
|
||
Teams</link> (http://wiki.openstack.org/SecurityTeams).
|
||
The Vulnerability Management process is fully documented
|
||
at <link
|
||
xlink:href="https://wiki.openstack.org/wiki/VulnerabilityManagement"
|
||
>Vulnerability
|
||
Management</link> (https://wiki.openstack.org/wiki/VulnerabilityManagement).</para>
|
||
</section>
|
||
<section xml:id="additional_info">
|
||
<title>Finding Additional Information</title>
|
||
<para>In addition to this book, there are many other sources
|
||
of information about OpenStack. The <link
|
||
|
||
xlink:href="http://www.openstack.org">OpenStack
|
||
website</link> (http://www.openstack.org) is a good
|
||
starting point, with <link
|
||
xlink:href="http://docs.openstack.org">OpenStack
|
||
Docs</link> (http://docs.openstack.org) and <link
|
||
|
||
xlink:href="http://api.openstack.org">OpenStack API
|
||
Docs</link> (http://api.openstack.org) providing
|
||
technical documentation about OpenStack. The <link
|
||
|
||
xlink:href="https://wiki.openstack.org">OpenStack
|
||
wiki</link> contains a lot of general information that
|
||
cuts across the OpenStack projects including a list of
|
||
<link
|
||
xlink:href="https://wiki.openstack.org/wiki/OperationsTools"
|
||
>recommended tools</link>
|
||
(https://wiki.openstack.org/wiki/OperationsTools ).
|
||
Finally, there are a number of blogs aggregated at <link
|
||
|
||
xlink:href="http://planet.openstack.org">Planet
|
||
OpenStack</link> (http://planet.openstack.org).</para>
|
||
</section>
|
||
|
||
</chapter>
|