Add a new library policy and process proposal
Quite often Oslo is requested to create (or adopt) new libraries for various purposes 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 or to become a new library that is independently maintained on pypi. Co-Authored-By: ChangBo Guo(gcb) <eric.guo@easystack.cn> Change-Id: Ib1ed8aad4859ca8313ac841fb9a57db1d08a2f10
This commit is contained in:
Joshua Harlow
ChangBo Guo(gcb)
parent
4fffcfd4bc
commit
1ad2d8fda4
@ -53,6 +53,7 @@ except ImportError:
|
||||
|
||||
exclude_patterns = [
|
||||
'**/graduation-template.rst',
|
||||
'**/new-library-template.rst',
|
||||
'**/template.rst',
|
||||
'**/policy-template.rst',
|
||||
]
|
||||
|
||||
116
specs/new-library-template.rst
Normal file
116
specs/new-library-template.rst
Normal 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
|
||||
|
||||
249
specs/policy/new-libraries.rst
Normal file
249
specs/policy/new-libraries.rst
Normal 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
|
||||
Loading…
x
Reference in New Issue
Block a user