From 70e2c88fddf2a3d37872e9c8b7abb6ae012289cd Mon Sep 17 00:00:00 2001 From: Goutham Pacha Ravi Date: Fri, 24 Apr 2020 18:24:06 -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: I1cc4c2f3d78e04a78dc46221e5edf786fd22a372 Story: #2007236 Task: #39554 Signed-off-by: Goutham Pacha Ravi --- CONTRIBUTING.rst | 23 +-- doc/source/admin/index.rst | 6 +- doc/source/contributor/contributing.rst | 57 ++++++- .../contributor/development-environment.rst | 151 ++++++++++++++++++ doc/source/contributor/features.rst | 11 +- doc/source/contributor/index.rst | 4 +- doc/source/contributor/testing.rst | 37 ----- doc/source/index.rst | 37 ++++- doc/source/install/installation.rst | 9 +- 9 files changed, 258 insertions(+), 77 deletions(-) create mode 100644 doc/source/contributor/development-environment.rst delete mode 100644 doc/source/contributor/testing.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index c075afe8..ad558339 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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 diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index bea32081..30417abf 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -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. diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst index 2aa07077..a0d1134a 100644 --- a/doc/source/contributor/contributing.rst +++ b/doc/source/contributor/contributing.rst @@ -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 `_ 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 +`_, 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. + +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 `_. + +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 diff --git a/doc/source/contributor/development-environment.rst b/doc/source/contributor/development-environment.rst new file mode 100644 index 00000000..57b54403 --- /dev/null +++ b/doc/source/contributor/development-environment.rst @@ -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 diff --git a/doc/source/contributor/features.rst b/doc/source/contributor/features.rst index e1f774dd..532d4f77 100644 --- a/doc/source/contributor/features.rst +++ b/doc/source/contributor/features.rst @@ -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. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 8b6c3414..dad6c0f1 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -3,8 +3,8 @@ Contributor Documentation ========================= .. toctree:: - :maxdepth: 2 + :maxdepth: 3 contributing - testing + development-environment features diff --git a/doc/source/contributor/testing.rst b/doc/source/contributor/testing.rst deleted file mode 100644 index 9f282e3a..00000000 --- a/doc/source/contributor/testing.rst +++ /dev/null @@ -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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 3bdb82f5..cf518dbb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 diff --git a/doc/source/install/installation.rst b/doc/source/install/installation.rst index 660a1a7c..084c04ca 100644 --- a/doc/source/install/installation.rst +++ b/doc/source/install/installation.rst @@ -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