[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,
|
||||
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
Normal file
56
doc/source/contributor/contributing.rst
Normal 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
|
||||
@ -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
|
||||
@ -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
|
||||
-------
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -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…
Reference in New Issue
Block a user