openstack/openstacksdk
Code Issues Proposed changes

Move the history lesson into the docs

Browse Source 
It's not really the most important thing now is it?

Change-Id: I3a595eb774bf04a53e1dd09484058ed148b6c122
This commit is contained in:
Monty Taylor 2019-08-01 10:14:21 -04:00
parent e702b020ca
commit b98e7098c8
3 changed files with 57 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
README.rst
View File

@ -14,61 +14,8 @@ write an application that talks to clouds no matter what crazy choices the
deployer has made in an attempt to be more hipster than their self-entitled
narcissist peers, then the Cloud Abstraction layer is for you.
A Brief History
---------------
.. TODO(shade) This history section should move to the docs. We can put a
link to the published URL here in the README, but it's too long.
openstacksdk started its life as three different libraries: shade,
os-client-config and python-openstacksdk.
``shade`` started its life as some code inside of OpenStack Infra's `nodepool`_
project, and as some code inside of the `Ansible OpenStack Modules`_.
Ansible had a bunch of different OpenStack related modules, and there was a
ton of duplicated code. Eventually, between refactoring that duplication into
an internal library, and adding the logic and features that the OpenStack Infra
team had developed to run client applications at scale, it turned out that we'd
written nine-tenths of what we'd need to have a standalone library.
Because of its background from nodepool, shade contained abstractions to
work around deployment differences and is resource oriented rather than service
oriented. This allows a user to think about Security Groups without having to
know whether Security Groups are provided by Nova or Neutron on a given cloud.
On the other hand, as an interface that provides an abstraction, it deviates
from the published OpenStack REST API and adds its own opinions, which may not
get in the way of more advanced users with specific needs.
``os-client-config`` was a library for collecting client configuration for
using an OpenStack cloud in a consistent and comprehensive manner, which
introduced the ``clouds.yaml`` file for expressing named cloud configurations.
``python-openstacksdk`` was a library that exposed the OpenStack APIs to
developers in a consistent and predictable manner.
After a while it became clear that there was value in both the high-level
layer that contains additional business logic and the lower-level SDK that
exposes services and their resources faithfully and consistently as Python
objects.
Even with both of those layers, it is still beneficial at times to be able to
make direct REST calls and to do so with the same properly configured
`Session`_ from `python-requests`_.
This led to the merge of the three projects.
The original contents of the shade library have been moved into
``openstack.cloud`` and os-client-config has been moved in to
``openstack.config``. Future releases of shade will provide a thin
compatibility layer that subclasses the objects from ``openstack.cloud``
and provides different argument defaults where needed for compatibility.
Similarly future releases of os-client-config will provide a compatibility
layer shim around ``openstack.config``.
.. _nodepool: https://docs.openstack.org/infra/nodepool/
.. _Ansible OpenStack Modules: http://docs.ansible.com/ansible/latest/list_of_cloud_modules.html#openstack
.. _Session: http://docs.python-requests.org/en/master/user/advanced/#session-objects
.. _python-requests: http://docs.python-requests.org/en/master/
More information about its history can be found at
https://docs.openstack.org/openstacksdk/latest/contributor/history.html
openstack
=========

48
doc/source/contributor/history.rst Normal file
View File

@ -0,0 +1,48 @@
A Brief History
===============
openstacksdk started its life as three different libraries: shade,
os-client-config and python-openstacksdk.
``shade`` started its life as some code inside of OpenStack Infra's `nodepool`_
project, and as some code inside of the `Ansible OpenStack Modules`_.
Ansible had a bunch of different OpenStack related modules, and there was a
ton of duplicated code. Eventually, between refactoring that duplication into
an internal library, and adding the logic and features that the OpenStack Infra
team had developed to run client applications at scale, it turned out that we'd
written nine-tenths of what we'd need to have a standalone library.
Because of its background from nodepool, shade contained abstractions to
work around deployment differences and is resource oriented rather than service
oriented. This allows a user to think about Security Groups without having to
know whether Security Groups are provided by Nova or Neutron on a given cloud.
On the other hand, as an interface that provides an abstraction, it deviates
from the published OpenStack REST API and adds its own opinions, which may not
get in the way of more advanced users with specific needs.
``os-client-config`` was a library for collecting client configuration for
using an OpenStack cloud in a consistent and comprehensive manner, which
introduced the ``clouds.yaml`` file for expressing named cloud configurations.
``python-openstacksdk`` was a library that exposed the OpenStack APIs to
developers in a consistent and predictable manner.
After a while it became clear that there was value in both the high-level
layer that contains additional business logic and the lower-level SDK that
exposes services and their resources faithfully and consistently as Python
objects.
Even with both of those layers, it is still beneficial at times to be able to
make direct REST calls and to do so with the same properly configured
`Session`_ from `python-requests`_.
This led to the merge of the three projects.
The original contents of the shade library have been moved into
``openstack.cloud`` and os-client-config has been moved in to
``openstack.config``.
.. _nodepool: https://docs.openstack.org/infra/nodepool/
.. _Ansible OpenStack Modules: http://docs.ansible.com/ansible/latest/list_of_cloud_modules.html#openstack
.. _Session: http://docs.python-requests.org/en/master/user/advanced/#session-objects
.. _python-requests: http://docs.python-requests.org/en/master/

9
doc/source/contributor/index.rst
View File

@ -10,8 +10,13 @@ About the Project
The OpenStack SDK is a OpenStack project aimed at providing a complete
software development kit for the programs which make up the OpenStack
community. It is a set of Python-based libraries, documentation, examples,
and tools released under the Apache 2 license.
community. It is a Python library with corresponding documentation,
examples, and tools released under the Apache 2 license.
.. toctree::
:maxdepth: 2
history
Contribution Mechanics
----------------------