Merge "Add a new library policy and process proposal"

This commit is contained in:
Zuul 2017-12-07 10:47:27 +00:00 committed by Gerrit Code Review
commit e030348dc6
3 changed files with 366 additions and 0 deletions

View File

@ -53,6 +53,7 @@ except ImportError:
exclude_patterns = [
'**/graduation-template.rst',
'**/new-library-template.rst',
'**/template.rst',
'**/policy-template.rst',
]

View File

@ -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:
<launchpad-id or None>
<launchpad-id or None>
Other contributors:
<launchpad-id or None>
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

View File

@ -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