Browse Source

[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 <gouthampravi@gmail.com>
changes/56/723056/1
Goutham Pacha Ravi 2 years ago
parent
commit
3c88e82871
  1. 22
      CONTRIBUTING.rst
  2. 56
      doc/source/contributor/contributing.rst
  3. 67
      doc/source/contributor/functional-tests.rst
  4. 12
      doc/source/contributor/index.rst
  5. 18
      doc/source/index.rst
  6. 2
      doc/source/user/api.rst

22
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

56
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 <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

67
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/<user>}
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 <user> 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.
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

@ -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
-------

18
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
<user/api>` (the :mod:`manilaclient` module), and a :doc:`command-line script
<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
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`

2
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: ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70>]
>>>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

Loading…
Cancel
Save