diff --git a/doc/source/conf.py b/doc/source/conf.py index 9dc2d76..930b6b8 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -53,6 +53,7 @@ except ImportError: exclude_patterns = [ '**/graduation-template.rst', + '**/new-library-template.rst', '**/template.rst', '**/policy-template.rst', ] diff --git a/specs/new-library-template.rst b/specs/new-library-template.rst new file mode 100644 index 0000000..5b8404a --- /dev/null +++ b/specs/new-library-template.rst @@ -0,0 +1,116 @@ +.. + 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. + +======================== +Proposed new library XXX +======================== + +Introduction paragraph -- why are we proposing new library? + +Proposed library mission +========================= + +A detailed description of the problem. + +Consuming projects +================== + +Who is going to use this (project involvement). + +Alternatives library +==================== + +Existing similar libraries (if any) and why they aren't being used + +Proposed adoption model/plan +============================ + +which adoption model the new library will choose ? + +Reviewer activity +================= +who will be responsible for reviewing, how many reviewers are active, +how many could be active. + +Implementation +============== + +Author(s) +--------- + +Who is leading the proposal of the new library? Must have at least two +individuals from the community committed to triaging and fixing bugs, and +responding to test failures in a timely manner. + +Primary authors: + + +Other contributors: + + +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/new-libraries.rst b/specs/policy/new-libraries.rst new file mode 100644 index 0000000..faa5c26 --- /dev/null +++ b/specs/policy/new-libraries.rst @@ -0,0 +1,249 @@ +============================= + Proposals for new libraries +============================= + +Quite often Oslo (as a group and project) is requested to create (or adopt) +new libraries for various purposes (some relevant, some not) and it would be +good to (as a group) have a stance on new libraries and the process they need +to go through to either become a new library in Oslo (that the Oslo group will +*own* and maintain going forward) or to become a new library that is +independently maintained on pypi (or some hybrid of both of these approaches). + +Problem Description +=================== + +Assume developer *Bob* wants to make a new library for project(s) in +OpenStack to consume. + +Bob at that point has a few options when building out this library: + +#. Keep the library independent from the Oslo project. Create library in + some repository site and produce a functional and useful artifact from + that library (typically a pypi release) and integrate it into the various + OpenStack projects once that artifact is created. + + Some **advantages** of this are: + + * Bob can work, release, iterate at his own pace. + * Wider python community adoption can start **immediately**. + + Some **disadvantages** of this are: + + * Hard to define/find purpose for a library when it is not initially + integrated into any project (typically to create a good library it + helps to have an active user of that library for feedback). + * Gamble in that adoption (in the larger python community or in + general) may not occur. + * No direct ability to take advantage of expertise (reviews, experience...) + developed in the wider Oslo group (aka the creator is on + his/her own). + +#. Create library in some repository site and produce a functional and useful + artifact from that library (typically a pypi release) and integrate it + into the various OpenStack projects (either by oneself or with others + to help) and then propose that the library be moved into the Oslo group's + ownership for some reasons like it's not maintained by owner but it is + used across OpenStack projects. + + Some **advantages** of this are (including prior option's advantages): + + * Continued maintenance (and reviews) of created library are now shared + among the oslo reviewers (and group). + + Some **disadvantages** of this are (including prior options disadvantages): + + * Continued maintenance (and reviews) of created library are now shared + among the oslo reviewers (and group). The creator may lose of control. + must follow Oslo's policies. + + There are also a few misconceptions about this approach that should also + be cleared up (these conceptions may have been previously warranted but + due to changes in the community they no longer should be deemed so): + + * Adoption in oslo does **not** guarantee success of a library (it will + still be a large amount of convincing and hard and dirty work to + be successful). + * The big tent makes it easier for a library to integrate into the + OpenStack ecosystems processes without having to join Oslo to also + benefit from that same ecosystems processes. + + Example **oslo** libraries that followed this workflow: + + * automaton + * futurist + +#. Create library immediately having the the Oslo group or subgroup (and by + default use the OpenStack ecosystem) help in its creation and produce a + functional and useful artifact from that library (typically a pypi + release) and integrate it into the various openstack projects. + + Some **advantages** of this are (including prior options advantages): + + * The expertise (years of experience, smart people) the Oslo group has + can help guide the libraries success. + * Continued maintenance (and reviews) of created library are now shared + among the Oslo reviewers (and group). The creator may lose of control, + since the project is now under Oslo's purview they can approve specs + and changes that creator might not agree with. + + Some **disadvantages** of this are (including prior options disadvantages): + + * Continued maintenance (and reviews) of created library are now shared + among the Oslo reviewers (and group). + * Same misconceptions as stated in previous item. + + Example **oslo** libraries that followed this workflow: + + * tooz + * debtcollector + * oslo.privsep + +#. Create library inside of a project, prove it is useful to its host + project (without becoming so specific to that host project that it is not + useful to anyone else) *then* extract that library to some repository site + and produce a useful artifact. Following this further maintenance at that + point will be via that repository site. + + Some **advantages** of this are: + + * Usefulness/purpose of the library will be more well-known due to + integration with a host project. + + Some **disadvantages** of this are: + + * Usefulness/purpose can be *too* specific to host project (and + further extraction/refactoring work will be needed to generalize). + + Example **oslo** libraries that followed this workflow: + + * taskflow + * oslo.versionedobjects + +#. Create source code in a host project, at a point where another host + project would benefit from that same code then extract source code into + a common incubator. At that point iterate over versions in that incubator + and periodically sync incubator version into host consuming projects. + At some point when deemed *stable* extract the incubators version into + a library and then produce a functional and useful artifact from that + library (typically a pypi release). Following this further maintenance at + that point will be via the new library repository site (and typically + versioning will be followed). + + Some **advantages** of this are: + + * Usefulness/purpose of the library will be more well-known due to + integration with a *set* of host projects. + + Some **disadvantages** of this are: + + * Typically a larger number of iterations required to extract a + isolated artifact. + * Multiple rounds of non-versioned syncing and potential + API collisions/conflicts (due to incubator copy/paste routine) and + change iteration. + * No ability for wider python community adoption from the get go. + * Harder to cleanup and track. + * Implementations will likely diverge and the amount of person time + required to keep in sync. + + Example **oslo** libraries that followed this workflow: + + * oslo.config + * oslo.cache + * oslo.concurrency + * oslo.db + * oslo.log + * oslo.messaging + * oslo.policy + * oslo.serialization + * ... + + +Bob will also have to pick which repository site he will use. For sake +of this document we will assume the majority will choose to use the OpenStack +ecosystems gerrit review system and git based hosting system (but Bob if +he desires can use something like github and pull requests if +he so chooses, as long as Bob takes into consideration that doing this +will be make it harder to get contributions from folks in the OpenStack +community). + +Proposed Policy +=============== + +In order to help Bob (or other author) make a *smart* selection from the +options listed above in the problem statement we as a group (who has +made these decisions many times previously) would like to +help new libraries (and their authors) become successful by having +new library proposals go through a sort of *litmus test* that we as a group +believe will help library creators figure out which of the above listed +options will be better suited for them (and be better suited for their own +library's future success). + +To aid in this process we as a group believe that when Bob (or other author) +starts to figure out which of the options he (or she) will take it would +be best for that developer to fill out the template new-library-template.rst +and post it for review on the openstack-dev mailing list with the [oslo] tag +in the subject. And then let the mailing list figure out which of the above +options will best work for the authors and the community as a whole). This +same information should also be proposed to the oslo-specs repository itself +(if/when the mailing list agrees that it should be a new oslo library). + +In order to make the new oslo library healthy and continuous development, +new core contributors for that adopted library are needed, it needs at least +two individuals from the community committed to triaging and fixing bugs, and +responding to test failures in a timely manner. + +Alternatives & History +====================== + +The other options are more along the line of what the Oslo group has +already done which is to have a sort of impromptu and tribal knowledge +around the area of new libraries and the options available to developers +wanting (and/or willing) to make new libraries. This policy will aim to +solidify that knowledge into a document that can be easily referenced and +agreed upon. + +Implementation +============== + +Author(s) +--------- + +Primary author: harlowja + +Other contributors: gcb + +Milestones +---------- + +Pike + +Work Items +---------- + +#. Draft policy +#. Get feedback on policy +#. Repeat +#. Approve policy + +References +========== + +* https://etherpad.openstack.org/p/newton-oslo-maybe-new-libraries + +Revision History +================ + +.. list-table:: Revisions + :header-rows: 1 + + * - Release Name + - Description + * - Pike + - Introduced + +.. note:: + + This work is licensed under a Creative Commons Attribution 3.0 + Unported License. + http://creativecommons.org/licenses/by/3.0/legalcode