- 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
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.
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 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.
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"]
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.