openstack/python-manilaclient
Code Issues Proposed changes

[ussuri][goal] Change contributor guide

Browse Source 
- Add a top level CONTRIBUTING.rst for
  repo browsers
- Refactor existing contributor guide
- Add a contributor/contributing.rst file
  with links back to relevant manila
  documentation.
- Rearrange some things in the main doc
  index file to make things prettier.

Change-Id: I68ea17a71c4ea1e7aac5bea1ec8b95344cb256b7
Story: #2007236
Task: #39553
Signed-off-by: Goutham Pacha Ravi <gouthampravi@gmail.com>
This commit is contained in:
Goutham Pacha Ravi 2020-04-24 16:49:52 -07:00
parent 3d4f0ba07d
commit 3c88e82871
6 changed files with 123 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
CONTRIBUTING.rst
View File

@ -1,16 +1,18 @@
If you would like to contribute to the development of OpenStack, The source repository for this project can be found at:
you must follow the steps documented at:
https://docs.openstack.org/infra/manual/developers.html https://opendev.org/openstack/python-manilaclient
Once those steps have been completed, changes to OpenStack Pull requests submitted through GitHub are not monitored.
should be submitted for review via the Gerrit tool, following
the workflow documented at:
https://docs.openstack.org/infra/manual/developers.html#development-workflow To start contributing to OpenStack, follow the steps in the contribution guide
to set up and use Gerrit:
Pull requests submitted through GitHub will be ignored. https://docs.openstack.org/contributors/code-and-documentation/quick-start.html
Bugs should be filed on Launchpad, not GitHub:
Bugs should be filed on Launchpad
https://bugs.launchpad.net/python-manilaclient https://bugs.launchpad.net/python-manilaclient
For more specific information about contributing to this repository, see the
python-manilaclient contributor guide:
https://docs.openstack.org/python-manilaclient/latest/contributor/contributing.html

56
doc/source/contributor/contributing.rst Normal file
View File

@ -0,0 +1,56 @@
============================
So You Want to Contribute...
============================
For general information on contributing to OpenStack, check out the
`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
It covers all the basics that are common to all OpenStack projects: the
accounts you need, the basics of interacting with our Gerrit review system,
how we communicate as a community, etc.
This project contains a python SDK and command line clients to interact with
the API exposed by `Manila <https://opendev.org/openstack/manila>`_,
the OpenStack Shared File Systems service. Refer to the `Contributor guide
for Manila <https://docs.openstack.org/manila/latest/contributor/contributing.html>`_
for information regarding the team's task trackers, communicating with other
project developers and contacting the core team.
Bugs
~~~~
You found an issue and want to make sure we are aware of it? You can do so on
`Launchpad <https://bugs.launchpad.net/python-manilaclient>`_.
If you're looking to contribute, search for the `low-hanging-fruit`_ tag to
see issues that are easier to get started with.
.. _project-structure:
Project Structure
~~~~~~~~~~~~~~~~~
This project includes three distinct components:
- manilaclient SDK: python bindings for Manila API `version V1`_ and
`version V2`_
- manilaclient shell: A `command line utility`_ (``manila``)
- OpenStack client shell: A `plugin to support the OpenStack Client`_
Command Line Interface.
The version 2 of the API for Manila supports microversions. The manilaclient
library is expected to handle these for complete backwards compatibility.
All versions of the Manila API are currently supported, however, future
releases of manilaclient may drop support for older versions of the API.
If you're working on the OpenStack Client command line interface plugin that
exists in this project, do read the `OpenStack Client Developer
Documentation`_. This includes the Human Interface Guide and some design
priciples including command structure and command specs that you will find
helpful.
.. _low-hanging-fruit: https://bugs.launchpad.net/python-manilaclient/+bugs?field.tag=low-hanging-fruit
.. _version V1: https://opendev.org/openstack/python-manilaclient/src/branch/master/manilaclient/v1
.. _version V2: https://opendev.org/openstack/python-manilaclient/src/branch/master/manilaclient/v2
.. _command line utility: https://opendev.org/openstack/python-manilaclient/src/branch/master/manilaclient/shell.py
.. _plugin to support the OpenStack Client: https://opendev.org/openstack/python-manilaclient/src/branch/master/manilaclient/osc
.. _OpenStack Client Developer Documentation: https://docs.openstack.org/python-openstackclient/latest/contributor/index.html

65
doc/source/contributor/functional-tests.rst
View File

@ -1,8 +1,9 @@
Functional tests Functional tests
================ ================
Manila contains a suite of functional tests under the There is a suite of functional tests under the
python-manilaclient/tests/functional directory. python-manilaclient/tests/functional directory. Unlike unit tests, these
tests perform API calls to Manila and are designed to run on a DevStack.
Adding functional tests to your changes is not mandatory but it's certainly Adding functional tests to your changes is not mandatory but it's certainly
a good practice and it's encouraged. a good practice and it's encouraged.
@ -10,10 +11,22 @@ a good practice and it's encouraged.
Prerequisite Prerequisite
------------ ------------
You need to have manila running somewhere. If you are using devstack, you can enable You need to have manila running somewhere. If you wish to use DevStack to
manila by enabling the manila plugin and selecting the backend you want to use. run manila, a good place to start would be the `manila contributor guide`_.
As an example, you can use the following local.conf file .. note::
We absolutely recommend using a ``fake shared file system back end`` as
opposed to a real storage system, because our tests are written with the
assumption that all APIs manila exposes are usable. In reality,
different real world storage back ends have `different capabilities`_ and
this project doesn't need to worry about them to provide a general purpose
interface to Manila. A fake driver provides fake storage, so don't
expect to be able to mount or use the shared file systems that you
create with it.
You can use the following local.conf file to configure DevStack including
Manila using a few fake back ends:
.. code-block:: console .. code-block:: console
@ -21,15 +34,15 @@ As an example, you can use the following local.conf file
# auth # auth
ADMIN_PASSWORD=nomoresecret ADMIN_PASSWORD=nomoresecret
DATABASE_PASSWORD=stackdb DATABASE_PASSWORD=$ADMIN_PASSWORD
RABBIT_PASSWORD=stackqueue RABBIT_PASSWORD=$ADMIN_PASSWORD
SERVICE_PASSWORD=$ADMIN_PASSWORD SERVICE_PASSWORD=$ADMIN_PASSWORD
# enable logging # enable logging for DevStack
LOGFILE=/opt/stack/logs/stack.sh.log LOGFILE=/opt/stack/logs/stack.sh.log
# Logging mode for DevStack services
VERBOSE=True VERBOSE=True
LOG_COLOR=True
LOGDIR=/opt/stack/logs
# manila # manila
enable_plugin manila https://opendev.org/openstack/manila enable_plugin manila https://opendev.org/openstack/manila
@ -37,10 +50,6 @@ As an example, you can use the following local.conf file
# python-manilaclient # python-manilaclient
LIBS_FROM_GIT=python-manilaclient LIBS_FROM_GIT=python-manilaclient
# versioning
PYTHON3_VERSION=3.6
IDENTITY_API_VERSION=3
# share driver # share driver
SHARE_DRIVER=manila.tests.share.drivers.dummy.DummyDriver SHARE_DRIVER=manila.tests.share.drivers.dummy.DummyDriver
@ -96,24 +105,23 @@ As an example, you can use the following local.conf file
MANILA_OPTGROUP_adminnet_standalone_network_plugin_allowed_ip_ranges=11.0.0.10-11.0.0.19,11.0.0.30-11.0.0.39,11.0.0.50-11.0.0.199 MANILA_OPTGROUP_adminnet_standalone_network_plugin_allowed_ip_ranges=11.0.0.10-11.0.0.19,11.0.0.30-11.0.0.39,11.0.0.50-11.0.0.199
MANILA_OPTGROUP_adminnet_network_plugin_ipv4_enabled=True MANILA_OPTGROUP_adminnet_network_plugin_ipv4_enabled=True
In this example we enable manila with the DummyDriver.
Configuration Configuration
------------- -------------
The functional tests require a couple of configuration files, so you will need to generate them yourself. The functional tests require a couple of configuration files, so you will need
to generate them before running the tests.
For devstack For DevStack
^^^^^^^^^^^^ ^^^^^^^^^^^^
If you are using devstack, you can run the following script On your DevStack machine, you can run the following script. It assumes that
``devstack`` is cloned onto your base folder.
.. code-block:: console .. code-block:: console
export HOME=${LOCAL:-/home/<user>} DEST=${DEST:-/opt/stack}
export DEST=${DEST:-/opt/stack} MANILACLIENT_DIR=${MANILACLIENT_DIR:-$DEST/python-manilaclient}
export MANILACLIENT_DIR=${MANILACLIENT_DIR:-$DEST/python-manilaclient} MANILACLIENT_CONF="$MANILACLIENT_DIR/etc/manilaclient/manilaclient.conf"
export MANILACLIENT_CONF="$MANILACLIENT_DIR/etc/manilaclient/manilaclient.conf"
# Go to the manilaclient dir # Go to the manilaclient dir
cd $MANILACLIENT_DIR cd $MANILACLIENT_DIR
# Give permissions # Give permissions
@ -177,15 +185,18 @@ If you are using devstack, you can run the following script
fi fi
Change <user> to the correct user value.
Running the tests Running the tests
----------------- -----------------
To run all functional tests make sure you are in the top level of your python-manilaclient To run all functional tests make sure you are in the top level of your
module (e.g. /opt/stack/python-manilaclient/) and simply run:: python-manilaclient module (e.g. /opt/stack/python-manilaclient/) and simply
run::
tox -e functional tox -e functional
This will create a virtual environment, load all the packages from This will create a virtual environment, load all the packages from
test-requirements.txt and run all functional tests. test-requirements.txt and run all functional tests.
.. _manila contributor guide: https://docs.openstack.org/manila/latest/contributor/development-environment-devstack.html
.. _different capabilities: https://docs.openstack.org/manila/latest/admin/share_back_ends_feature_support_mapping.html

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

@ -1,13 +1,13 @@
Contributing Contributing
============ ============
Code is hosted at `opendev.org`_. Submit bugs to the Basic Information
python-manilaclient project on `Launchpad`_. Submit code to the -----------------
openstack/python-manilaclient project using `Gerrit`_.
.. _opendev.org: https://opendev.org/openstack/python-manilaclient .. toctree::
.. _Launchpad: https://launchpad.net/python-manilaclient :maxdepth: 3
.. _Gerrit: https://docs.openstack.org/infra/manual/developers.html#development-workflow
contributing
Testing Testing
------- -------

18
doc/source/index.rst
View File

@ -4,39 +4,39 @@ Python bindings to the OpenStack Manila API
This is a client for OpenStack Manila API. There's :doc:`a Python API This is a client for OpenStack Manila API. There's :doc:`a Python API
<user/api>` (the :mod:`manilaclient` module), and a :doc:`command-line script <user/api>` (the :mod:`manilaclient` module), and a :doc:`command-line script
<user/shell>` (installed as :program:`manila`). Each implements the entire <user/shell>` (installed as :program:`manila`). Each implements the entire
OpenStack Manila API. OpenStack Manila API. See :ref:`project-structure` for more information.
You'll need credentials for an OpenStack cloud that implements the You'll need credentials for an OpenStack cloud that implements the
Manila API in order to use the manila client. Manila API in order to use the manila client.
Command-Line Reference Command-Line Reference
====================== ~~~~~~~~~~~~~~~~~~~~~~
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
user/shell user/shell
API Using the python module
=== ~~~~~~~~~~~~~~~~~~~~~~~
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
user/api user/api
Contributing Contributing
============ ~~~~~~~~~~~~
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
contributor/index contributor/index
.. only:: html .. only:: html
Indices and tables Indices and tables
================== ~~~~~~~~~~~~~~~~~~
* :ref:`genindex` * :ref:`genindex`
* :ref:`search` * :ref:`search`

2
doc/source/user/api.rst
View File

@ -22,7 +22,7 @@ done so, you can use the API like so::
ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70 ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70
>>> manila.shares.list() >>> manila.shares.list()
[<Share: ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70>] [<Share: ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70>]
>>>share.delete >>> share.delete
In addition to creating and deleting shares, the manilaclient can manage In addition to creating and deleting shares, the manilaclient can manage
share-types, access controls, and more! Using CephFS with Ganesha for NFS share-types, access controls, and more! Using CephFS with Ganesha for NFS