From 3c88e8287102c4e5ca6c88a11c4ca0f5b0faec72 Mon Sep 17 00:00:00 2001 From: Goutham Pacha Ravi Date: Fri, 24 Apr 2020 16:49:52 -0700 Subject: [PATCH] [ussuri][goal] Change contributor guide - 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 --- CONTRIBUTING.rst | 22 ++++--- doc/source/contributor/contributing.rst | 56 +++++++++++++++++ doc/source/contributor/functional-tests.rst | 67 ++++++++++++--------- doc/source/contributor/index.rst | 12 ++-- doc/source/index.rst | 18 +++--- doc/source/user/api.rst | 2 +- 6 files changed, 123 insertions(+), 54 deletions(-) create mode 100644 doc/source/contributor/contributing.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 3c0d8244d..a3e931e60 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,16 +1,18 @@ -If you would like to contribute to the development of OpenStack, -you must follow the steps documented at: +The source repository for this project can be found at: - https://docs.openstack.org/infra/manual/developers.html + https://opendev.org/openstack/python-manilaclient -Once those steps have been completed, changes to OpenStack -should be submitted for review via the Gerrit tool, following -the workflow documented at: +Pull requests submitted through GitHub are not monitored. - 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. - -Bugs should be filed on Launchpad, not GitHub: + https://docs.openstack.org/contributors/code-and-documentation/quick-start.html +Bugs should be filed on Launchpad 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 diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 000000000..45bcb6c34 --- /dev/null +++ b/doc/source/contributor/contributing.rst @@ -0,0 +1,56 @@ +============================ +So You Want to Contribute... +============================ + +For general information on contributing to OpenStack, check out the +`contributor guide `_ 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 `_, +the OpenStack Shared File Systems service. Refer to the `Contributor guide +for Manila `_ +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 `_. + +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 \ No newline at end of file diff --git a/doc/source/contributor/functional-tests.rst b/doc/source/contributor/functional-tests.rst index d03c7e5ef..0425acd5a 100644 --- a/doc/source/contributor/functional-tests.rst +++ b/doc/source/contributor/functional-tests.rst @@ -1,8 +1,9 @@ Functional tests ================ -Manila contains a suite of functional tests under the -python-manilaclient/tests/functional directory. +There is a suite of functional tests under the +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 a good practice and it's encouraged. @@ -10,10 +11,22 @@ a good practice and it's encouraged. Prerequisite ------------ -You need to have manila running somewhere. If you are using devstack, you can enable -manila by enabling the manila plugin and selecting the backend you want to use. +You need to have manila running somewhere. If you wish to use DevStack to +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 @@ -21,15 +34,15 @@ As an example, you can use the following local.conf file # auth ADMIN_PASSWORD=nomoresecret - DATABASE_PASSWORD=stackdb - RABBIT_PASSWORD=stackqueue + DATABASE_PASSWORD=$ADMIN_PASSWORD + RABBIT_PASSWORD=$ADMIN_PASSWORD SERVICE_PASSWORD=$ADMIN_PASSWORD - # enable logging + # enable logging for DevStack LOGFILE=/opt/stack/logs/stack.sh.log + + # Logging mode for DevStack services VERBOSE=True - LOG_COLOR=True - LOGDIR=/opt/stack/logs # 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 LIBS_FROM_GIT=python-manilaclient - # versioning - PYTHON3_VERSION=3.6 - IDENTITY_API_VERSION=3 - # share driver 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_network_plugin_ipv4_enabled=True -In this example we enable manila with the DummyDriver. - 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 - export HOME=${LOCAL:-/home/} - export DEST=${DEST:-/opt/stack} - export MANILACLIENT_DIR=${MANILACLIENT_DIR:-$DEST/python-manilaclient} - export MANILACLIENT_CONF="$MANILACLIENT_DIR/etc/manilaclient/manilaclient.conf" + DEST=${DEST:-/opt/stack} + MANILACLIENT_DIR=${MANILACLIENT_DIR:-$DEST/python-manilaclient} + MANILACLIENT_CONF="$MANILACLIENT_DIR/etc/manilaclient/manilaclient.conf" # Go to the manilaclient dir cd $MANILACLIENT_DIR # Give permissions @@ -177,15 +185,18 @@ If you are using devstack, you can run the following script fi -Change to the correct user value. - Running the tests ----------------- -To run all functional tests make sure you are in the top level of your python-manilaclient -module (e.g. /opt/stack/python-manilaclient/) and simply run:: +To run all functional tests make sure you are in the top level of your +python-manilaclient module (e.g. /opt/stack/python-manilaclient/) and simply +run:: tox -e functional This will create a virtual environment, load all the packages from -test-requirements.txt and run all functional tests. \ No newline at end of file +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 \ No newline at end of file diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 25e912c2e..2b6fd9439 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -1,13 +1,13 @@ Contributing ============ -Code is hosted at `opendev.org`_. Submit bugs to the -python-manilaclient project on `Launchpad`_. Submit code to the -openstack/python-manilaclient project using `Gerrit`_. +Basic Information +----------------- -.. _opendev.org: https://opendev.org/openstack/python-manilaclient -.. _Launchpad: https://launchpad.net/python-manilaclient -.. _Gerrit: https://docs.openstack.org/infra/manual/developers.html#development-workflow +.. toctree:: + :maxdepth: 3 + + contributing Testing ------- diff --git a/doc/source/index.rst b/doc/source/index.rst index 54a5cd22c..9df60f13a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 ` (the :mod:`manilaclient` module), and a :doc:`command-line script ` (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 Manila API in order to use the manila client. Command-Line Reference -====================== +~~~~~~~~~~~~~~~~~~~~~~ .. toctree:: - :maxdepth: 1 + :maxdepth: 2 user/shell -API -=== +Using the python module +~~~~~~~~~~~~~~~~~~~~~~~ .. toctree:: - :maxdepth: 1 + :maxdepth: 2 user/api Contributing -============ +~~~~~~~~~~~~ .. toctree:: - :maxdepth: 1 + :maxdepth: 2 contributor/index .. only:: html Indices and tables - ================== + ~~~~~~~~~~~~~~~~~~ * :ref:`genindex` * :ref:`search` diff --git a/doc/source/user/api.rst b/doc/source/user/api.rst index c923520bf..8c67f998d 100644 --- a/doc/source/user/api.rst +++ b/doc/source/user/api.rst @@ -22,7 +22,7 @@ done so, you can use the API like so:: ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70 >>> manila.shares.list() [] - >>>share.delete + >>> share.delete In addition to creating and deleting shares, the manilaclient can manage share-types, access controls, and more! Using CephFS with Ganesha for NFS