From 7760f4a2eccda2ad704ed6486e53defc4c63ea71 Mon Sep 17 00:00:00 2001 From: Ben Nemec Date: Thu, 7 Jul 2016 21:55:01 +0000 Subject: [PATCH] Add expedited approvals policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In general, TripleO follows the standard “2 +2” review standard, but there are situations where we want to make an exception. This policy is intended to document those exceptions. It has recently come to my attention that not all reviewers are on the same page regarding some of our review policies, so this is my attempt to document it in a reviewable location. Some of this information is already on the wiki, but that is not easy for the team to review before changes are made and is probably going away in the future. Since this is not a release-specific document, I've added a new section to our specs index for cross-release policies like this. It is based on the oslo-specs policy section. I would anticipate this being useful for other policy type information in the future, especially as the wiki is being phased out. Change-Id: Ie2d357813ebc194a94ee26464d6882a6d8abe13a --- doc/source/conf.py | 1 + doc/source/index.rst | 12 +++ specs/policy-template.rst | 126 +++++++++++++++++++++++++++ specs/policy/expedited-approvals.rst | 93 ++++++++++++++++++++ 4 files changed, 232 insertions(+) create mode 100644 specs/policy-template.rst create mode 100644 specs/policy/expedited-approvals.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index a7d9ebe3..6e84f174 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -34,6 +34,7 @@ feed_author = 'OpenStack TripleO Team' exclude_patterns = [ '**/template.rst', + '**/policy-template.rst', ] # autodoc generation is a bit aggressive and a nuisance when doing heavy diff --git a/doc/source/index.rst b/doc/source/index.rst index 5f4d654b..cebfe427 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -36,6 +36,18 @@ Juno Approved Specs: specs/juno/* +======================== +TripleO Project Policies +======================== + +Team decisions and policies that are not limited to a specific release. + +.. toctree:: + :glob: + :maxdepth: 1 + + specs/policy/* + ================== Indices and tables ================== diff --git a/specs/policy-template.rst b/specs/policy-template.rst new file mode 100644 index 00000000..442d35d5 --- /dev/null +++ b/specs/policy-template.rst @@ -0,0 +1,126 @@ +.. + This template should be in ReSTructured text. For help with syntax, + see http://sphinx-doc.org/rest.html + + To test out your formatting, build the docs using tox, or see: + http://rst.ninjs.org + + The filename in the git repository should match the launchpad URL, + for example a URL of + https://blueprints.launchpad.net/oslo?searchtext=awesome-thing should be + named awesome-thing.rst. + + For specs targeted at a single project, please prefix the first line + of your commit message with the name of the project. For example, + if you're submitting a new feature for oslo.config, your git commit + message should start something like: "config: My new feature". + + Wrap text at 79 columns. + + Do not delete any of the sections in this template. If you have + nothing to say for a whole section, just write: None + + If you would like to provide a diagram with your spec, ascii diagrams are + required. http://asciiflow.com/ is a very nice tool to assist with making + ascii diagrams. The reason for this is that the tool used to review specs is + based purely on plain text. Plain text will allow review to proceed without + having to look at additional files which can not be viewed in gerrit. It + will also allow inline feedback on the diagram itself. + +========================= + The title of the policy +========================= + +Introduction paragraph -- why are we doing anything? + +Problem Description +=================== + +A detailed description of the problem. + +Policy +====== + +Here is where you cover the change you propose to make in detail. How do you +propose to solve this problem? + +If the policy seeks to modify a process or workflow followed by the +team, explain how and why. + +If this is one part of a larger effort make it clear where this piece ends. In +other words, what's the scope of this policy? + +Alternatives & History +====================== + +What other ways could we do this thing? Why aren't we using those? This doesn't +have to be a full literature review, but it should demonstrate that thought has +been put into why the proposed solution is an appropriate one. + +If the policy changes over time, summarize the changes here. The exact +details are always available by looking at the git history, but +summarizing them will make it easier for anyone to follow the desired +policy and understand when and why it might have changed. + +Implementation +============== + +Author(s) +--------- + +Who is leading the writing of the policy? If more than one person is +working on it, please designate the primary author and contact. + +Primary author: + + +Other contributors: + + +Milestones +---------- + +When will the policy go into effect? + +If there is a built-in deprecation period for the policy, or criteria +that would trigger it no longer being in effect, describe them. + +Work Items +---------- + +List any concrete steps we need to take to implement the policy. + +References +========== + +Please add any useful references here. You are not required to have +any references. Moreover, this policy should still make sense when +your references are unavailable. Examples of what you could include +are: + +* Links to mailing list or IRC discussions + +* Links to notes from a summit session + +* Links to relevant research, if appropriate + +* Related policies as appropriate + +* Anything else you feel it is worthwhile to refer to + +Revision History +================ + +.. list-table:: Revisions + :header-rows: 1 + + * - Release Name + - Description + * - + - Introduced + +.. note:: + + This work is licensed under a Creative Commons Attribution 3.0 + Unported License. + http://creativecommons.org/licenses/by/3.0/legalcode diff --git a/specs/policy/expedited-approvals.rst b/specs/policy/expedited-approvals.rst new file mode 100644 index 00000000..afc8b476 --- /dev/null +++ b/specs/policy/expedited-approvals.rst @@ -0,0 +1,93 @@ +===================== + Expedited Approvals +===================== + +In general, TripleO follows the standard "2 +2" review standard, but there are +situations where we want to make an exception. This policy is intended to +document those exceptions. + +Problem Description +=================== + +Core reviewer time is precious, and there is never enough of it. In some +cases, requiring 2 +2's on a patch is a waste of that core time, so we need +to be reasonable about when to make exceptions. While core reviewers are +always free to use their judgment about when to merge or not merge a patch, +it can be helpful to list some specific situations where it is acceptable and +even expected to approve a patch with a single +2. + +Part of this information is already in the wiki, but the future of the wiki +is in doubt and it's better to put policies in a place that they can be +reviewed anyway. + +Policy +====== + +A core can and should approve patches without a second +2 under the following +circumstances: + +* The change has multiple +2's on previous patch sets, indicating an agreement + from the other cores that the overall design is good, and any alterations to + the patch since those +2's must be minor implementation details only - + trivial rebases, minor syntax changes, or comment/documentation changes. +* Backports proposed by another core reviewer. Backports should already have + been reviewed for design when they merged to master, so if two cores agree + that the backport is good (one by proposing, the other by reviewing), they + can be merged with a single +2 review. +* Requirements updates proposed by the bot. + +Note that this policy does not affect CI requirements. Patches must still +pass CI before merging. + +Alternatives & History +====================== + +This policy has been in effect for a while now, but not every TripleO core is +aware of it, so it is simply being written down in an official location for +reference. + +Implementation +============== + +Author(s) +--------- + +Primary author: + bnemec + +Milestones +---------- + +The policy is already in effect. + +Work Items +---------- + +Ensure all cores are aware of the policy. Once the policy has merged, an email +should be sent to openstack-dev referring to it. + +References +========== + +Existing wiki on review guidlines: +https://wiki.openstack.org/wiki/TripleO/ReviewGuidelines + +Previous spec that implemented some of this policy: +http://specs.openstack.org/openstack/tripleo-specs/specs/kilo/tripleo-review-standards.html + +Revision History +================ + +.. list-table:: Revisions + :header-rows: 1 + + * - Release Name + - Description + * - Newton + - Introduced + +.. note:: + + This work is licensed under a Creative Commons Attribution 3.0 + Unported License. + http://creativecommons.org/licenses/by/3.0/legalcode