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