Jump to: navigation, search

Difference between revisions of "Documentation/InstallGuide"

m (Meeting information)
Line 94: Line 94:
 
* '''Tom Fifield''', fighting for the users
 
* '''Tom Fifield''', fighting for the users
 
* '''Haïkel Guémar''', RDO maintainer, will act as a liaison.
 
* '''Haïkel Guémar''', RDO maintainer, will act as a liaison.
 +
* '''Petr Kovar''', interested in RDO specific content
 
* '''Name''', role/interests
 
* '''Name''', role/interests
  

Revision as of 14:18, 17 February 2016

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

The OpenStack 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. Assuming a bug involves an actual problem with the installation guide, contributing a patch, and approving that patch without further investigation (which may sometimes require testing) carries a significant risk of breaking the guide, often in obscure ways. To keep the installation guide operational, we must use the following best practices 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

Every two weeks (on even weeks) on Wednesday at 0100 UTC in #openstack-meeting-3
Every two weeks (on odd weeks) on Tuesday at 1300 UTC in #openstack-meeting-3

NB This schedule is currently under discussion in the openstack-docs mailing list and may change.

Install Team meeting information

Agenda for next meeting

Logs from past meetings

Team members

  • Christian Berendt, team lead; interested in 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)
  • 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.
  • 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
  • Haïkel Guémar, RDO maintainer, will act as a liaison.
  • Petr Kovar, interested in RDO specific content
  • Name, role/interests

Link archive