grian-ui/README.rst

grian-ui - telemetry visualization dashboard

• Free software: Apache license
• Documentation: https://docs.openstack.org/grian-ui/latest/
• Release notes: https://docs.openstack.org/releasenotes/grian-ui/
• Source: https://opendev.org/openstack/grian-ui
• Bugs: https://bugs.launchpad.net/grian-ui

move to contributor docs.

Making Changes & Contributing

This project uses pre-commit, and tox please make sure to install them before making any changes:

cd grian_ui
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install pre-commit tox git-review
pre-commit install --install-hooks

It is a good practice for maintainers to update the hooks to the latest version every few months. this can be done with:

pre-commit autoupdate

and submitting a commit. when updating the hooks it may be necessary to address new issues found. To make ci pass these issues should be fixed in the same commit that makes the change however you should avoid making unrelated fixes in the same patch.

This project uses tox to execute tests, build docs and automate other development task that are not suitable for automation via pre-commit.

Running Tests

This repo currently has 3 type of tests but more may follow

First unit tests can be run with your envs default python like this :

``tox -e py3``  or  ``tox -e unit``

it also possible to you a non default python version by specifying a version sufix :

tox -e py312

The second type of testing is functional testing. Where as unit tests should be short and test individual functions. Functional tests should avoid mocking code in the plugin but can use fixtures or other fakes/proxy to replace external systems like a fake datasoures that returns static data or emulates an openstack service like keystone.

functional tests can be run in a similar way to unit tests :

``tox -e functional`` or ``tox -e functional-py312``

The third type of testing we have today are style/lint checks. there are 3 ways to run these checks first with tox :

``tox -e pep8`` or ``tox -e lint``

by convention in openstack we use a pep8 tox env to execute all our style and linting checks not just pep8. in many other communities this is often called lint so we support both.

internally both targets are identical and call pre-commit to run the style checks. So the third way to run the style checks is with pre-commit directly:

``pre-commit run -a``

or if you have the hooks installed they will run automatically when you commit a change. If you ever want to override that behavior you can do:

#skip all checks
git commit --no-verify

or

# skip a single check
SKIP=hacking git commit

.. NOTE::

  unit, functional and style checks are enforced by our zuul
  CI system so if they don't pass your code cant merge.
  CI just run the tox command the same as you can do locally
  so its encouraged to run them locally first.

DOCS

docs are built via tox envs that wrap a tool called sphinx. At present we have two types of docs, general docs are stored in the doc folder and release notes that are generated by the reno tool are stored in the releasenotes directory. As can be seen form this README we use a format called reStructuredText to write all our docs.

The main docs can be built with either tox -e docs or tox -e pdf-docs depending on the desired format. Note that to be able to build PDF docs in particular you may need to install binary depencies on your system. These can be found in bindep.txt in the doc and pdf-docs profiles.

The second type of docs we have are the release notes. New release-notes can be added by executing tox -e venv -- reno new your-note-name-here and built with tox -e releasenotes

Note

The venv example above demonstrates that many tox envs support taking additional parameter that can be passed to the underlying tools. In the case of the venv target it will create a virtual enve with all the runtime test and docs depencies installed so tools such as sphinx, reno, manage.py can all be used from that env. For the unit and functional envs additional parameters can be passed to stestr to contol how tests are run such as a text regex.

Running Grian-UI for development

Work in progress.

This will evolve overtime but as of this moment its possible to run Grian-UI in horizon by running tox -e runserver. This can also be done manually via tox -e venv -- ./manage.py runserver

For this to be useful you will need to have openstack which can be deployed with devstack or any other tool. A sample local.conf <devstack/local.conf-all-in-one> is provided in the devstack plugin.

This local.conf expect the following file at /opt/stack/prometheus.yml :

global:
  scrape_interval: 10s
scrape_configs:
  - job_name: "node"
    static_configs:
      - targets: ["localhost:3000"]

enable Grian-UI when we add any content. and move the devstack exampel to the devstack plugin

if you are running devstack on a remote vm you can forward the development server endpoint locally using the following command :

ssh -N -L 8000:localhost:8000 <user@host>

This will create an ssh session and forward localhost:8000 on the remote system to localhost:8000 on your local system. -N prevents allocating a shell for the ssh session while not required it recommended to use a dedicated ssh command to forward ports.