From d330e5a49055edd3c4613d4d095de6ef9a777426 Mon Sep 17 00:00:00 2001 From: bria4010 Date: Wed, 29 Jun 2016 18:17:53 -0400 Subject: [PATCH] Update to Glance Contributor's docs * add mention of Glance contrib guidelines to CONTRIBUTING.rst * update info about api-ref docs now being in-tree * add disallowed minor code change doc * database scripts, as agreed on at 2016-06-23 meeting * non-type-safe changes to tests Change-Id: I1e997efe72828d99626f5b7f2e2f7c96cae8da98 --- CONTRIBUTING.rst | 7 +++- doc/source/contributing/documentation.rst | 19 +++++++++-- doc/source/contributing/index.rst | 1 + .../contributing/minor-code-changes.rst | 33 +++++++++++++++++++ 4 files changed, 56 insertions(+), 4 deletions(-) create mode 100644 doc/source/contributing/minor-code-changes.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 8fe8d5479e..fa6ac802c9 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,7 +1,7 @@ If you would like to contribute to the development of OpenStack, you must follow the steps in documented at: - http://docs.openstack.org/infra/manual/developers.html#development-workflow + http://docs.openstack.org/infra/manual/developers.html#getting-started Once those steps have been completed, changes to OpenStack should be submitted for review via the Gerrit tool, following @@ -14,3 +14,8 @@ Pull requests submitted through GitHub will be ignored. Bugs should be filed on Launchpad, not GitHub: https://bugs.launchpad.net/glance + +Additionally, specific guidelines for contributing to Glance may be found in +Glance's Documentation: + + http://docs.openstack.org/developer/glance/contributing diff --git a/doc/source/contributing/documentation.rst b/doc/source/contributing/documentation.rst index 37a8856f2f..e24ffe130d 100644 --- a/doc/source/contributing/documentation.rst +++ b/doc/source/contributing/documentation.rst @@ -35,10 +35,23 @@ which you may want to contribute: * OpenStack API Reference - There are some Glance-related API quick-reference guides published by the - OpenStack Documentation Team. Please see the README in their code repository - for more information: https://github.com/openstack/api-site + There's a "quick reference" guide to the APIs implemented by Glance: + http://developer.openstack.org/api-ref/image/ + The guide is generated from source files in the source code tree under + ``api-ref/source``. Corrections in spelling or typographical errors may be + addressed directly by a patch. If you note a divergence between the API + reference and the actual behavior of Glance, please file a bug before + submitting a patch. + + Additionally, now that the quick reference guides are being maintained by + each project (rather than a central team), you may note divergences in format + between the Glance guides and those of other teams. For example, some + projects may have adopted an informative new way to display error codes. If + you notice structural improvements that our API reference is missing, please + file a bug. And, of course, we would also welcome your patch implementing + the improvement! + Release Notes ------------- diff --git a/doc/source/contributing/index.rst b/doc/source/contributing/index.rst index 826a1a5711..5086a14efb 100644 --- a/doc/source/contributing/index.rst +++ b/doc/source/contributing/index.rst @@ -13,6 +13,7 @@ Policies blueprints documentation + minor-code-changes .. bugs contributor-onboarding core-reviewers diff --git a/doc/source/contributing/minor-code-changes.rst b/doc/source/contributing/minor-code-changes.rst new file mode 100644 index 0000000000..c760edf6a3 --- /dev/null +++ b/doc/source/contributing/minor-code-changes.rst @@ -0,0 +1,33 @@ +Disallowed Minor Code Changes +============================= + +There are a few types of code changes that have been proposed recently that +have been rejected by the Glance team, so we want to point them out and explain +our reasoning. + +If you feel an exception should be made for some particular change, please put +it on the agenda for the Glance weekly meeting so it can be discussed. + +Database migration scripts +-------------------------- + +Once a database script has been included in a release, spelling or grammar +corrections in comments are forbidden unless you are fixing them as a part of +another stronger bug on the migration script itself. Modifying migration +scripts confuses operators and administrators -- we only want them to notice +serious problems. Their preference must take precedence over fixing spell +errors. + +Tests +----- + +Occasionally someone proposes a patch that converts instances of +``assertEqual(True, whatever)`` to ``assertTrue(whatever)``, or instances of +``asertEqual(False, w)`` to ``assertFalse(w)`` in tests. Note that these are +not type safe changes and they weaken the tests. (See the Python ``unittest`` +docs for details.) We tend to be very conservative about our tests and don't +like weakening changes. + +We're not saying that such changes can never be made, we're just saying that +each change must be accompanied by an explanation of why the weaker test is +adequate for what's being tested.