Merge "Add a new library policy and process proposal"
This commit is contained in:
commit
e030348dc6
|
@ -53,6 +53,7 @@ except ImportError:
|
||||||
|
|
||||||
exclude_patterns = [
|
exclude_patterns = [
|
||||||
'**/graduation-template.rst',
|
'**/graduation-template.rst',
|
||||||
|
'**/new-library-template.rst',
|
||||||
'**/template.rst',
|
'**/template.rst',
|
||||||
'**/policy-template.rst',
|
'**/policy-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:
|
||||||
|
<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
|
||||||
|
|
|
@ -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
|
Loading…
Reference in New Issue