Jump to: navigation, search

Difference between revisions of "Documentation/InstallGuide"

(→‎How to contribute)
Line 6: Line 6:
 
== How to contribute ==
 
== How to contribute ==
  
−
WIP
+
Contrary to most other OpenStack documentation, the installation guide includes a precise series of instructions to install a complex software suite. The primary audience involves people unfamiliar with OpenStack who simply want to evaluate it with minimal hassle and frustration. To meet these requirements, we (the contributors) thoroughly test the installation guide to verify functionality prior to a release and periodically thereafter to catch minor issues, usually involving changes to packaging.
 +
 
 +
Over the last several releases, the installation guide has become mature enough that most [https://bugs.launchpad.net/openstack-manuals/+bugs bugs] involve user error rather than problems with the installation guide. Simply assuming a bug involves an actual problem with the installation guide, contributing a patch, and approving that patch without further investigation (sometimes involving testing) carries a significant chance of breaking the guide, often in obscure ways. To keep the installation guide operational, we must use the following procedure to properly triage bugs, contribute, and review patches:
 +
 
 +
=== Bugs ===
 +
# Do not confirm or triage your own bug. Wait for someone on the installation guide sub-team to change the status or initiate a discussion about it.
 +
# Do not confirm or triage a bug unless you can verify an actual problem with the installation guide. In some cases, the bug description provides enough information to make a quick decision, but most of the time requires discussion or testing in a lab environment prior to confirming or triaging it.
 +
# For the most part, only members of the installation guide sub-team should triage a bug.
 +
 
 +
=== Patches ===
 +
# Do not contribute a patch for a bug without triage status.
 +
 
 +
=== Reviews ===
 +
# Do not vote +1/+2 or approve a patch that references a bug without triage.
 +
# If a patch lacks reference to a bug, vote -1 and notify the contributor to correct the commit message.
 +
# If any doubt exists with a patch, initiate discussion and/or test it in a lab environment prior to voting +1/+2 or approving it.
 +
# For the most part, only members of the installation guide sub-team should vote +2 or approve a patch.
 +
 
 +
=== Examples ===
 +
 
 +
To improve clarity of bug triage policy and processes, please review the following bugs:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Bug !! Discussion
 +
|-
 +
|  [https://bugs.launchpad.net/openstack-manuals/+bug/1482523 1482523] ||
 +
* Involves an error with keystone, a service that all other services use. If an actual problem with the installation guide, we should see more than one of these bugs.
 +
* In most cases, a 500 error indicates user error, typically skipping a step or making a typo in the configuration.
 +
|-
 +
| [https://bugs.launchpad.net/openstack-manuals/+bug/1495396 1495396] ||
 +
* Involves lack of sufficient reading. The content that the reporter indicates as missing actually exists on both the neutron controller and compute node pages under the *To configure Compute to use Networking* header.
 +
|-
 +
| [https://bugs.launchpad.net/openstack-manuals/+bug/1497415 1497415] ||
 +
* Involves a potential packaging problem. We should not need to correct directory or file permissions.
 +
* Consider testing this issue in a lab environment, otherwise request that the reporter open a bug for their particular supplier of packages. In this case, RDO.
 +
|-
 +
| [https://bugs.launchpad.net/openstack-manuals/+bug/1469228 1469228] ||
 +
* Reporter unaware that keystone uses the same endpoint version for API v2.0 and v3. If an actual problem with the installation guide, we should see more than one of these bugs.
 +
|-
 +
| [https://bugs.launchpad.net/openstack-manuals/+bug/1484104 1484104] ||
 +
* I doubt this cinder issue has anything to do with keystone, otherwise the services prior to cinder such as glance, nova, and neutron would fail to operate.
 +
|-
 +
| [https://bugs.launchpad.net/openstack-manuals/+bug/1491507 1491507] [https://bugs.launchpad.net/openstack-manuals/+bug/1490963 1490963] ||
 +
* Two bugs from different people regarding the same issue generally indicates a problem rather than user error. However, we should not need to correct directory or file permissions problem.
 +
* Consider testing this issue in a lab environment, otherwise request that the reporter open a bug for their particular supplier of packages. In this case, RDO.
 +
* Considering the importance of this service and general lack of response to packaging bugs by packagers, consider adding a temporary workaround to the installation guide.
 +
|-
 +
| [https://bugs.launchpad.net/openstack-manuals/+bug/1497538 1497538] ||
 +
* Bugs that involve issues with location of arguments in client commands generally indicate a client version problem.
 +
* Request that the reporter check the client version. The version must match the version provided by the distribution package, not an upstream (source) version.
 +
|-
 +
| [https://bugs.launchpad.net/openstack-manuals/+bug/1495287 1495287] ||
 +
* Involves lack of sufficient reading. Instruction clearly indicates creating the file prior to editing it.
 +
|-
 +
| [https://bugs.launchpad.net/openstack-manuals/+bug/1490064 1490064] ||
 +
* Although the reporter found the problem, be aware of bugs that reference distribution versions (such as Fedora 22) or alternative infrastructure services (such as PostgreSQL) that the installation guide does not explicitly support.
 +
|-
 +
|}
  
 
== Quick links ==
 
== Quick links ==

Revision as of 15:41, 23 September 2015

Welcome to the home page for the Install Guide Specialty Team!

About the Install Guide team

Specialty team for developing and maintaining the OpenStack Install Guide.

How to contribute

Contrary to most other OpenStack documentation, the installation guide includes a precise series of instructions to install a complex software suite. The primary audience involves people unfamiliar with OpenStack who simply want to evaluate it with minimal hassle and frustration. To meet these requirements, we (the contributors) thoroughly test the installation guide to verify functionality prior to a release and periodically thereafter to catch minor issues, usually involving changes to packaging.

Over the last several releases, the installation guide has become mature enough that most bugs involve user error rather than problems with the installation guide. Simply assuming a bug involves an actual problem with the installation guide, contributing a patch, and approving that patch without further investigation (sometimes involving testing) carries a significant chance of breaking the guide, often in obscure ways. To keep the installation guide operational, we must use the following procedure to properly triage bugs, contribute, and review patches:

Bugs

  1. Do not confirm or triage your own bug. Wait for someone on the installation guide sub-team to change the status or initiate a discussion about it.
  2. Do not confirm or triage a bug unless you can verify an actual problem with the installation guide. In some cases, the bug description provides enough information to make a quick decision, but most of the time requires discussion or testing in a lab environment prior to confirming or triaging it.
  3. For the most part, only members of the installation guide sub-team should triage a bug.

Patches

  1. Do not contribute a patch for a bug without triage status.

Reviews

  1. Do not vote +1/+2 or approve a patch that references a bug without triage.
  2. If a patch lacks reference to a bug, vote -1 and notify the contributor to correct the commit message.
  3. If any doubt exists with a patch, initiate discussion and/or test it in a lab environment prior to voting +1/+2 or approving it.
  4. For the most part, only members of the installation guide sub-team should vote +2 or approve a patch.

Examples

To improve clarity of bug triage policy and processes, please review the following bugs:

Bug Discussion
1482523
  • Involves an error with keystone, a service that all other services use. If an actual problem with the installation guide, we should see more than one of these bugs.
  • In most cases, a 500 error indicates user error, typically skipping a step or making a typo in the configuration.
1495396
  • Involves lack of sufficient reading. The content that the reporter indicates as missing actually exists on both the neutron controller and compute node pages under the *To configure Compute to use Networking* header.
1497415
  • Involves a potential packaging problem. We should not need to correct directory or file permissions.
  • Consider testing this issue in a lab environment, otherwise request that the reporter open a bug for their particular supplier of packages. In this case, RDO.
1469228
  • Reporter unaware that keystone uses the same endpoint version for API v2.0 and v3. If an actual problem with the installation guide, we should see more than one of these bugs.
1484104
  • I doubt this cinder issue has anything to do with keystone, otherwise the services prior to cinder such as glance, nova, and neutron would fail to operate.
1491507 1490963
  • Two bugs from different people regarding the same issue generally indicates a problem rather than user error. However, we should not need to correct directory or file permissions problem.
  • Consider testing this issue in a lab environment, otherwise request that the reporter open a bug for their particular supplier of packages. In this case, RDO.
  • Considering the importance of this service and general lack of response to packaging bugs by packagers, consider adding a temporary workaround to the installation guide.
1497538
  • Bugs that involve issues with location of arguments in client commands generally indicate a client version problem.
  • Request that the reporter check the client version. The version must match the version provided by the distribution package, not an upstream (source) version.
1495287
  • Involves lack of sufficient reading. Instruction clearly indicates creating the file prior to editing it.
1490064
  • Although the reporter found the problem, be aware of bugs that reference distribution versions (such as Fedora 22) or alternative infrastructure services (such as PostgreSQL) that the installation guide does not explicitly support.

Quick links

Meeting information

Meetings are weekly on Tuesdays at 13:00 UTC (8:00 AM US CDT)
For the month of August, we are alternating meeting times; the meetings on the 11 and 25 August will be at 23:00 UTC (6:00 PM US CDT)

Previous meetings

Team members

  • Karin Levenstein, team lead
  • Bernd Bausch, interested in more readable and complete install guides
  • Pranav Salunke, interested in maintaining openSUSE, SLES sections of installa guides. Also creating tools for automated testing and making it easy to work on install guides.
  • Christian Berendt, migration to RST, automated testing and updating (screenshots, outputs), no preference for a distribution (can take care of Fedora/RHEL/CentOS, this is my primary set of distributions)
  • Matt Kassawara, doing this for a while now.
  • Alex Adamov, Debian
  • Karen Bradshaw, help convert the install guide to RST
  • Harry Sutton, interested in maintaining currency and accuracy in the install guides. I work for HP in Technology Services and worry about things like serviceability.
  • Brian Moss, interested in improving the guides
  • Tom Fifield, fighting for the users
  • Name, role/interests

Link archive

Retrieved from "https://wiki.openstack.org/w/index.php?title=Documentation/InstallGuide&oldid=90896"