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: I1cc4c2f3d78e04a78dc46221e5edf786fd22a372
Story: #2007236
Task: #39554
Signed-off-by: Goutham Pacha Ravi <gouthampravi@gmail.com>
changes/59/723059/2
Goutham Pacha Ravi 1 year ago
parent
commit
70e2c88fdd
9 changed files with 258 additions and 77 deletions
  1. +13
    -10
      CONTRIBUTING.rst
  2. +3
    -3
      doc/source/admin/index.rst
  3. +53
    -4
      doc/source/contributor/contributing.rst
  4. +151
    -0
      doc/source/contributor/development-environment.rst
  5. +6
    -5
      doc/source/contributor/features.rst
  6. +2
    -2
      doc/source/contributor/index.rst
  7. +0
    -37
      doc/source/contributor/testing.rst
  8. +29
    -8
      doc/source/index.rst
  9. +1
    -8
      doc/source/install/installation.rst

+ 13
- 10
CONTRIBUTING.rst View File

@ -1,16 +1,19 @@
If you would like to contribute to the development of OpenStack,
you must follow the steps in this page:
The source repository for this project can be found at:
https://docs.openstack.org/infra/manual/developers.html
https://opendev.org/openstack/manila-ui
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.
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/manila-ui
https://bugs.launchpad.net/manila-ui
For more specific information about contributing to this repository, see the
manila-ui contributor guide:
https://docs.openstack.org/manila-ui/latest/contributor/contributing.html

+ 3
- 3
doc/source/admin/index.rst View File

@ -1,6 +1,6 @@
====================
Administration Guide
====================
===================
Administrator Guide
===================
Shares are file storage that instances can access. Users can
allow or deny a running instance to have access to a share at any time.


+ 53
- 4
doc/source/contributor/contributing.rst View File

@ -1,4 +1,53 @@
============
Contributing
============
.. include:: ../../../CONTRIBUTING.rst
============================
So You Want to Contribute...
============================
For general information on contributing to OpenStack, please 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 plug-in to the OpenStack Dashboard (Horizon). It
adds functionality to the OpenStack Dashboard to interact with `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.
See :doc:`development-environment` for details about how to bootstrap a
development environment and test manila-ui.
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/manila-ui>`_.
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 two dashboard components:
- `administrator dashboard`_
- `user dashboard`_
The administrator dashboard extends the OpenStack Dashboard's administrator
interface by adding ``Share`` (short for ``Shared File Systems``) functionality
to manage Share and Share Group Types, Share servers and other
`administrator-only` components of the Shared File System service. It also
extends the functionality of the Identity service to allow controlling
Shared File System service quotas.
The User dashboard provides all user facing functionality.
.. _low-hanging-fruit: https://bugs.launchpad.net/manila-ui/+bugs?field.tag=low-hanging-fruit
.. _administrator dashboard: https://opendev.org/openstack/manila-ui/src/branch/master/manila_ui/dashboards/admin
.. _user dashboard: https://opendev.org/openstack/manila-ui/src/branch/master/manila_ui/dashboards/project

+ 151
- 0
doc/source/contributor/development-environment.rst View File

@ -0,0 +1,151 @@
.. _development-environment:
====================
Developing manila-ui
====================
For simple documentation and code fixes, you don't need a comprehensive test
environment with this project's main dependencies such as manila,
python-manilaclient and horizon. Before submitting any code fixes for review,
you can run :ref:`unit-tests` locally. To try your changes with manila-ui and
Horizon and all other dependencies, we recommend the use of DevStack.
DevStack
--------
DevStack can help you setup a simple development environment for developing and
testing manila-ui. Read the section about DevStack in the `manila
contributor guide`_.
.. note::
We absolutely recommend using a ``fake shared file system back end`` as
opposed to a real storage system to experience the full capabilities of
manila UI. Manila UI is built 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 graphical user 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 and manila-ui using a few fake back ends:
.. code-block:: console
[[local|localrc]]
# auth
ADMIN_PASSWORD=nomoresecret
DATABASE_PASSWORD=$ADMIN_PASSWORD
RABBIT_PASSWORD=$ADMIN_PASSWORD
SERVICE_PASSWORD=$ADMIN_PASSWORD
# enable logging for DevStack
LOGFILE=/opt/stack/logs/stack.sh.log
# Logging mode for DevStack services
VERBOSE=True
# manila
enable_plugin manila https://opendev.org/openstack/manila
# manila-ui
enable_plugin manila-ui https://opendev.org/openstack/manila-ui
# python-manilaclient
LIBS_FROM_GIT=python-manilaclient
# share driver
SHARE_DRIVER=manila.tests.share.drivers.dummy.DummyDriver
# share types
MANILA_DEFAULT_SHARE_TYPE_EXTRA_SPECS='snapshot_support=True create_share_from_snapshot_support=True revert_to_snapshot_support=True mount_snapshot_support=True'
MANILA_CONFIGURE_DEFAULT_TYPES=True
# backends and groups
MANILA_ENABLED_BACKENDS=alpha,beta,gamma,delta
MANILA_CONFIGURE_GROUPS=alpha,beta,gamma,delta,membernet,adminnet
# alpha
MANILA_OPTGROUP_alpha_share_driver=manila.tests.share.drivers.dummy.DummyDriver
MANILA_OPTGROUP_alpha_driver_handles_share_servers=True
MANILA_OPTGROUP_alpha_share_backend_name=ALPHA
MANILA_OPTGROUP_alpha_network_config_group=membernet
MANILA_OPTGROUP_alpha_admin_network_config_group=adminnet
# beta
MANILA_OPTGROUP_beta_share_driver=manila.tests.share.drivers.dummy.DummyDriver
MANILA_OPTGROUP_beta_driver_handles_share_servers=True
MANILA_OPTGROUP_beta_share_backend_name=BETA
MANILA_OPTGROUP_beta_network_config_group=membernet
MANILA_OPTGROUP_beta_admin_network_config_group=adminnet
# gamma
MANILA_OPTGROUP_gamma_share_driver=manila.tests.share.drivers.dummy.DummyDriver
MANILA_OPTGROUP_gamma_driver_handles_share_servers=False
MANILA_OPTGROUP_gamma_share_backend_name=GAMMA
MANILA_OPTGROUP_gamma_replication_domain=DUMMY_DOMAIN
# delta
MANILA_OPTGROUP_delta_share_driver=manila.tests.share.drivers.dummy.DummyDriver
MANILA_OPTGROUP_delta_driver_handles_share_servers=False
MANILA_OPTGROUP_delta_share_backend_name=DELTA
MANILA_OPTGROUP_delta_replication_domain=DUMMY_DOMAIN
# membernet
MANILA_OPTGROUP_membernet_network_api_class=manila.network.standalone_network_plugin.StandaloneNetworkPlugin
MANILA_OPTGROUP_membernet_standalone_network_plugin_gateway=10.0.0.1
MANILA_OPTGROUP_membernet_standalone_network_plugin_mask=24
MANILA_OPTGROUP_membernet_standalone_network_plugin_network_type=vlan
MANILA_OPTGROUP_membernet_standalone_network_plugin_segmentation_id=1010
MANILA_OPTGROUP_membernet_standalone_network_plugin_allowed_ip_ranges=10.0.0.10-10.0.0.209
MANILA_OPTGROUP_membernet_network_plugin_ipv4_enabled=True
# adminnet
MANILA_OPTGROUP_adminnet_network_api_class=manila.network.standalone_network_plugin.StandaloneNetworkPlugin
MANILA_OPTGROUP_adminnet_standalone_network_plugin_gateway=11.0.0.1
MANILA_OPTGROUP_adminnet_standalone_network_plugin_mask=24
MANILA_OPTGROUP_adminnet_standalone_network_plugin_network_type=vlan
MANILA_OPTGROUP_adminnet_standalone_network_plugin_segmentation_id=1011
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
Once your DevStack is ready, you can log into the OpenStack Dashboard and
explore the ``Share`` dashboards under `Project` and `Admin` sections that are
included due to manila-ui.
See the `Horizon user guide`_ for instructions regarding logging into the
OpenStack Dashboard.
.. _unit-tests:
Running unit tests
------------------
The unit tests can be executed directly from within this Manila UI plugin
project directory by using::
$ cd ../manila-ui
$ tox
This is made possible by the dependency in test-requirements.txt upon the
horizon source, which pulls down all of the horizon and openstack_dashboard
modules that the plugin uses.
To run only py3 unit tests, use following command::
$ tox -e py3
To run unit tests using specific Django version use the following::
$ tox -e py3-dj22
$ tox -e py3-dj110
.. _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
.. _Horizon user guide: https://docs.openstack.org/horizon/latest/user/log-in.html

+ 6
- 5
doc/source/contributor/features.rst View File

@ -1,6 +1,6 @@
============
New Features
============
===================
Adding New Features
===================
When implementing a new feature, you may think about making it optional,
so it could be enabled or disabled in different deployments.
@ -31,6 +31,7 @@ the following template:
.. code-block:: none
manila_ui[/tests]/path/to/directory/tests.py
manila_ui/tests/path/to/directory/tests.py
Manila UI tests use the mock library for testing.
Manila UI tests use the ``mock`` module from the ``unittest`` package for
unit testing.

+ 2
- 2
doc/source/contributor/index.rst View File

@ -3,8 +3,8 @@ Contributor Documentation
=========================
.. toctree::
:maxdepth: 2
:maxdepth: 3
contributing
testing
development-environment
features

+ 0
- 37
doc/source/contributor/testing.rst View File

@ -1,37 +0,0 @@
=======
Testing
=======
Starting the app
----------------
If everything has gone according to plan, you should be able to run:
.. code-block:: console
./run_tests.sh --runserver 0.0.0.0:8080
and have the application start on port 8080. The horizon dashboard will
be located at http://localhost:8080/
Running unit tests
------------------
The unit tests can be executed directly from within this Manila UI plugin
project directory by using::
$ cd ../manila-ui
$ tox
This is made possible by the dependency in test-requirements.txt upon the
horizon source, which pulls down all of the horizon and openstack_dashboard
modules that the plugin uses.
To run only py3 unit tests, use following command::
$ tox -e py3
To run unit tests using specific Django version use the following::
$ tox -e py3-dj22
$ tox -e py3-dj110

+ 29
- 8
doc/source/index.rst View File

@ -1,22 +1,43 @@
.. manila-ui documentation master file, created by
sphinx-quickstart on Tue Jul 9 22:26:36 2013.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
.. the main title comes from README.rst
http://www.apache.org/licenses/LICENSE-2.0
.. include:: ../../README.rst
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Contents
--------
=======================================
manila-ui - Manila Management Dashboard
=======================================
.. toctree::
:maxdepth: 2
install/installation
.. toctree::
:maxdepth: 2
configuration/index
.. toctree::
:maxdepth: 1
user/index
.. toctree::
:maxdepth: 1
admin/index
.. toctree::
:maxdepth: 2
contributor/index
.. only:: html


+ 1
- 8
doc/source/install/installation.rst View File

@ -2,14 +2,6 @@
Installation
============
DevStack Installation
---------------------
Add this repo as an external repository into your ``local.conf`` file::
[[local|localrc]]
enable_plugin manila-ui https://opendev.org/openstack/manila-ui
Manual Installation
-------------------
@ -27,6 +19,7 @@ And enable it in Horizon.::
cp ../manila-ui/manila_ui/local/enabled/_*.py openstack_dashboard/local/enabled
cp ../manila-ui/manila_ui/local/local_settings.d/_90_manila_*.py openstack_dashboard/local/local_settings.d
.. _install-rdo:
Installing Manila UI in RDO


Loading…
Cancel
Save