============================================ 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 .. TODO:: 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. .. _pre-commit: https://pre-commit.com/ .. _tox: https://tox.wiki 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. .. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html 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 ` 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"] .. TODO:: 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 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.