[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>
This commit is contained in:
Goutham Pacha Ravi
parent
3d4f0ba07d
commit
3c88e82871
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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
|
||||||
-------
|
-------
|
||||||
|
|
|
||||||
|
|
@ -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`
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue