Contribution guide

Contribution guide#

Error reporting#

  • Create a new issue: issues/new

    • Describe relevant details that you think might be related to the issue (like initial conditions, environment variables, etc).

    • Don’t forget to specify what version of SSH Monitor you are using.

    • Try to provide a minimal example that will reproduce the error.

    • Do not hesitate to share logs, screenshots or any other interesting files/information.

Improvements and features suggestions#

  • Create a new issue: issues/new

    • Describe what improvements/features you would like to see coming.

    • Explain how those improvements/features would positively change the way you use SSH Monitor.

General work process#

  • As much as possible, work on the specified SSH Monitor issues. The priority issues are the ones specified in the upcoming milestones. If you want to work on a subject that is not contained in an existing issue, then create an issue first.

  • Before working on an issue, make sure that this issue is attached to a milestone. If not, add it to an existing milestone or create a new one.

  • Before working on an issue, make sure that the associated milestone has a dedicated Git branch (and dont forget to switch to it).

  • When creating new Git commits, please end your commit message with a newline referencing the issue you are working on (e.g. end with see #123, check this commit as an example).

  • Before closing an issue, make sure that:

    • The HMIs have been updated and tested.

    • The documentation has been updated.

    • The tests have been updated and still pass.

Release checklist#

The versioning convention to follow is semver.

🚧 ?TODO? 🚧 git-cliff?

  • Create a milestone for an upcoming release. E.g. see milestone v2.1.0.

  • Create a dedicated branch associated to the milestone. E.g. see milestones_v2.1.0.

    For example:

    $ git switch -c v1.2.3

  • Add/create issues associated to the milestone. E.g. see the issues of the milestone v2.1.0

  • Solve every issues associated to the milestone.

  • Before merging the milestone branch, one or several last commits should be pushed in order to make sure that:

    • The HMIs have been updated and tested.

    • The documentation has been updated.

    • The tests have been updated and still pass.

    • The changelog file is up to date.
      Each issue addressed in the milestone should be referenced here.

    • The project layout file is up to date.

    • The links in the documentation have been checked with markdown-link-check:

      $ find ./documentation -name "*.md" -not -path "./documentation/.site/*" -print0 | xargs -0 -n1 markdown-link-check -p

    • The README.md and the documentation directory are up to date.

    • The tests are up to date and are passing with the following command:

      $ nix flake check

    • The CI does not break.

    • The PROJECT_NUMBER, in the doxyfile.conf, has been updated to the current milestone version.

    • The version, in the conf.py, has been updated to the current milestone version.

    • The version, in the pyproject.toml, has been updated to the current milestone version.

    • The Doxygen documentation has been re-generated against that new milestone version.

    • The Sphinx documentation has been re-generated against that new milestone version.

    • The GitLab pages have been updated accordingly.

  • Create a new Merge Request (e.g. like the merge request for v2.1.0)

    • Add at least one reviewer to the MR (ideally not yourself) and wait for review(s): change your MR accordingly.

    • Once the reviewer(s) approves your MR, merge it.

  • Once the MR is merged, tag the latest commit of this MR (e.g. v2.1.0).

  • Once the tag has been created, submit a new release associated to this tag (dont forget to check “Include message from the annotated tag.”) and associated to the milestone.

  • Close the milestone.

Documentation#

  • Follow the documentation convention: https://diataxis.fr/

  • Prerequisites:

    • Doxygen (1.11+)

    • Poetry (1.8+)

      • After installing Poetry with your package manager, don’t forget to run poetry install at the root of the SSH Monitor project.

  • Semantic Line Break

  • CommonMark

  • Doxygen

    • $ doxygen documentation/.doxygen/doxyfile.conf

    • Make sure there is no warning nor error in the Doxygen output.

    • Note that Doxygen will use the scripts located in the filter-patterns-scripts directory directory in order to trick Doxygen into thinking that .substitutions and .template files have a syntax similar to Python files.

    • Note that the configuration file used by Doxygen – in this project – is doxyfile.conf.

    • Note that Doxygen will use the layout doxygen_layout.xml in order to rearrange the generated HTML and LaTeX pages. In particular the “Detailed Description” section is put on top (this has been done by moving the <detaileddescription title=""/> tag of the original layout generated with doxygen -l).

    • Note that Doxygen will use filter patterns scripts (through the FILTER_PATTERNS option of doxyfile.conf). Here, those scripts are used to trick Doxygen into thinking that EPICS .template and .substitutions files are valid Python files, in order to get a clearer Doxygen documentation for the EPICS App.

  • Sphinx

    • $ poetry run sphinx-build --fail-on-warning --keep-going --fresh-env --write-all --jobs auto --builder html ./documentation ./documentation/.site

    • Make sure there is no warning nor error in the Sphinx output.

    • Then you can check how the Sphinx documentation renders in your web browser (e.g. Firefox): $ firefox ./documentation/.site/index.html

  • Spelling and phrasing

    • vale --config='.vale.ini' --glob='*.md' ./documentation/*

  • No broken link objectif:

    • Extract every gitlab link and check them in order to make sure they are up to date.

    • Every time an internet-link is added to the documentation, please make sure that the link points to the associate web archive (wayback machine) page.

      E.g. if you have a link to: https://epics-docs-mj-test.readthedocs.io/projects/epics-base/en/latest/record-reference.html

      then – instead – add a link to: web.archive:20240612143143/https://epics-docs-mj-test.readthedocs.io/projects/epics-base/en/latest/record-reference.html

    • Check links availability of the documentation with markdown-link-check:

      $ cd ./documentation
$ find . -name \*.md -print0 | xargs -0 -n1 markdown-link-check -p

  • Each new .substitutions file file must:

    • have a dedicated recommended how-to

    • have a dedicated reference page

    • appear in the documentation everywhere other .substitutions files are mentioned

Developments#

Tests#

  • How to run the quick tests with epics v7 (with the optional builders option):

    $ sudo nix build -L ".#checks.x86_64-linux.quick-tests-with-epics-v7" --builders "@$XDG_CONFIG_HOME/nix/build_servers"

  • How to run the full tests with epics v7 (with the optional builders option):

    $ sudo nix build -L ".#checks.x86_64-linux.full-tests-with-epics-v7" --builders "@$XDG_CONFIG_HOME/nix/build_servers"

  • How to run all the tests (with epics v3 and v7):

    $ nix flake check

  • How to access the tests VMs and play with them:

    $ nix build ".#checks.x86_64-linux.full-tests-with-epics-v7.driverInteractive" -L
$ ./result/bin/nixos-test-driver # this executable will open the below Python shell

    ...
>>> start_all() # start all VMs
...
>>> test_script() # run tests
...
>>> host_machine.succeed("ip a")
...
>>> intermediate_machine.succeed("ip a")
...
>>> target_machine.succeed("ip a")
...
>>> host_machine.shell_interact() # access to a shell running inside a VM
...

    Caution

    In this case, make sure you are using a terminal that won’t “suck” the windows that it might open. So it’s not recommended to use terminals like st, it is preferred to use terminals like alacritty. Otherwise, when running the start_all() command, the VMs windows might pop up and replace the terminal in which you ran nixos-test-driver, thus preventing you from running subsequent commands like test_script(), <machine-name>.succeed(), <machine-name>.shell_interact(), etc.

  • Let’s say you are interactively testing an IOC running on a VM. How to access it from your local machine (e.g. with Phoebus, or caget/caput)? In order to do so, run the following Python commands:

    >>> host_machine.send_monitor_command(f"hostfwd_add tcp::5064-:5064")
...
>>> host_machine.send_monitor_command(f"hostfwd_add udp::5064-:5064")
...
>>> host_machine.send_monitor_command(f"hostfwd_add tcp::5065-:5065")
...
>>> host_machine.send_monitor_command(f"hostfwd_add udp::5065-:5065")
...
>>> host_machine.succeed("systemctl stop firewall")
...

  • How to re-use the VMs states coming from a previous run:

    $ ./result/bin/nixos-test-driver --keep-vm-state

    ...

    (just use the --keep-vm-state flag)

    The machine state is stored in the $TMPDIR/vm-state-machine-name directory.

  • Important

    When including new shell instructions in .substitutions files, do not forget to also specify them in the Python test scripts (by setting up the restricted shell accordingly)!

Training#

  • How to build the training VM? The associated Nix code is located in the ./training-vm directory, and will produce an .ova file for VirtualBox:

    $ nix build -L ".#training-vm"

    The resulting .ova file can be found in ./result/nixos-12.34.yyyymmdd.hash-x86_64-linux.ova.

Contents