diff --git a/README.rst b/README.rst index cbd532db7..3f01b050c 100644 --- a/README.rst +++ b/README.rst @@ -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 ========= diff --git a/doc/source/contributor/history.rst b/doc/source/contributor/history.rst new file mode 100644 index 000000000..02a43f754 --- /dev/null +++ b/doc/source/contributor/history.rst @@ -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/ diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 1e871335b..d9573fde1 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -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 ----------------------