From 4300ff9579fb4f61d619af01c42af6a8278fd530 Mon Sep 17 00:00:00 2001 From: Dawa Ometto Date: Thu, 25 Jul 2024 10:18:07 +0200 Subject: [PATCH] docs: modernize the item quality list --- docs/index.md | 6 ++- docs/item_quality_checklist.md | 96 +++++++++++++++++----------------- 2 files changed, 52 insertions(+), 50 deletions(-) diff --git a/docs/index.md b/docs/index.md index 524b6004..e2f8ce77 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,14 +2,16 @@ This is the developer documentation for this repository. See [primer SURF ResearchCloud](https://utrechtuniversity.github.io/vre-docs/docs/research-cloud-intro.html) for end-user documentation). -This documentation concern ResearchCloud components for Unix/Linux workspaces, which are based on Ansible. There is a [separate repository](https://github.com/UtrechtUniversity/researchcloud-items-win/) for Windows components (using PowerShell). - Below is a section for [playbooks](#Playbooks) and a section for [roles](#Roles) (reusable items that can be included in a playbook). The playbook and roles can be used stand-alone (run them locally on the target host), but are designed with the goal of deploying them in the deployment of a ResearchCloud workspace. Contributed playbooks and roles should meet criteria specified in our [item quality checklist](./item_quality_checklist.md). +### A note on Windows + +This documentation concern ResearchCloud components for Unix/Linux workspaces, which are based on Ansible. There is a [separate repository](https://github.com/UtrechtUniversity/researchcloud-items-win/) for Windows components (using PowerShell). + ## Installing as a collection The roles and playbooks in this repository can also be installed as an Ansible collection. The collection is named `uusrc.general`. After installation, this means you can use the roles from this repository, for example as follows: diff --git a/docs/item_quality_checklist.md b/docs/item_quality_checklist.md index b5611949..0a33b494 100644 --- a/docs/item_quality_checklist.md +++ b/docs/item_quality_checklist.md @@ -1,48 +1,34 @@ # Item Quality Checklist Below list can be used to check the quality of your ResearchCloud-items software and documentation. +## Documentation + +### Components + +Components in the ResearchCloud catalog should contain a brief description: + +- name and contact information for the author/maintainer of the item or component. +- link to developer documentation (e.g. to this repository). + +For Ansible-based Components (see [here](./index.md#a-note-on-windows) for more info), both the *playbooks* and the *roles* utilized by the playbook should be documented. + +### Catalog Items + +ResearchCloud _catalog items_ are effectively compositions that reference various components. Catalog items should be described in the ResearchCloud catalog itself, including: -## Documentation -### Location -As a general guideline, documentation must be maintained in the same environment and as-close-as-possible to -related program source code. This guideline aims to protect consistency between source code and documentation. - -The guideline translates to the following concrete requirements: -- catalog items listed in the SURF ResearchCloud catalog are effectively composition specifications (= programs) that reference -catalog components. Hence these composition items should be documented in the catalog itself. -- catalog components merely reference externally held installation scripts. Their "Ansible Playbook" -scripts are located elsewhere, in a Git repository (such as this one). The component/playbook documentation should be maintained in -that Git repository. It suffices to have the catalog component document a refererence to the URL of the documentation in the -Git repository. Any other descriptive catalog component information should be derived from the documentation kept in Git. -- Ansible Roles should be documented in the Git repository that lists their source code. - -### Content -As a general guideline, documentation concerning catalog items should -target end users. Documentation for catalog components should target developers/integrators. - -Next to descriptive information, the ResearchCloud catalog should document at least for each catalog item/component: - name and contact information for the author/maintainer of the item or component -- indication of provided level of support to users ("Status: Experimental, use with care" or "Status: Supported") -- url of documentation (as mentioned in above paragraph) +- link to enduser documentation. For UU Catalog Items, this documentation can be found at https://utrechtuniversity.github.io/vre-docs/docs/workspace-catalogue.html +- a brief description + +The description field should provide: -Catalog items should, in addition to the above, also provide: -- indication of suitability ("Suitability: non-sensitive data only", "Suitability: sensitive data") +- indication of suitability ("Suitability: non-sensitive data only", "Suitability: sensitive data") - indication of maintenance level ("Maintenance: automated (security) patches configured", -"Maintenance: User must manually apply (security) patches") +"Maintenance: User must manually apply (security) patches") - information on required or recommended workspace dimensions (e.g. cores, memory, operating system version) - list of any other user responsibilities, if any -- information on any monitoring services that are included (e.g. vulnerability scanning of software) - -## Git documentation format -When adding documentation to the Git repository, please consider to format your text -using the file [template-playbooks.md](playbooks/template-playbooks.md) to -document a playbook -or the file [template-roles.md](roles/template-roles.md) to document a role. - -NB: The files section of roles may include [base64 encoded](icons.md) icon files. -These files can be used to decorate a related catalog item in -SURF ResearchCloud. - +- information on any monitoring services that are included (e.g. vulnerability scanning of software) +- if the item is experimental or not yet fully supported, this should be clear from the description or subtitle. ## Functionality Scope Ansible Playbooks (ResearchCloud components) should be able to run independent of any other Playbooks. This guideline @@ -62,7 +48,7 @@ For more information, see [Design Principles](./design_principles.md). Avoid the use of hardcoded constants or literals in installation scripts. Instead, always reference an Ansible variable and include a default value for such variable in the Role specification. -Parameters provided to Ansible Playbooks must follow the naming conventions for SURF ResearchCloud items. +Parameters provided to Ansible Playbooks must follow the naming conventions for SURF ResearchCloud items. ## Reusability Source code must always be accompanied by an explicit License. It suffices to mention a common license applicable to the @@ -74,11 +60,15 @@ part of a European Research program. It assists you to select an appropriate and ## Support and Maintenance -A Catalog item/component should be marked either "experimental" or "supported". -Supported items/components are expected to be actively maintained and proactively checked for any defects on an annual basis -or more frequent. They have been tested in use case workspace compositions. -They must be fully documented according to the specifications in this guideline. -Supported catalog items may not comprise of any catalog components that are experimental. + +Supported catalog items and components: + +- are expected to be actively maintained and proactively checked for any defects, for instance through automated testing. +- they have been tested in use case workspace compositions. +- they must be fully documented according to the specifications in this guideline. +- supported catalog items may not comprise of any catalog components that are experimental. + +Components should be set to *Public* (usable by all Collaborative Organisations) only if they meet the above criteria. Unsupported items/components should include a disclaimer to indicate their experimental status. This alerts end users to double-check compliance with policies. @@ -92,17 +82,27 @@ A workspace composition should be compliant with applicable policies. When in do workspace type to a specified community/collaboration. ## Best practices + ### Test-driven development -While unit tests are not present in these components made for SURF Research Cloud, there are other tools that can help you: [Ansible testing modules](https://docs.ansible.com/ansible/latest/reference_appendices/test_strategies.html), [Ansible Lint](https://ansible-lint.readthedocs.io/en/latest/) and [Ansible Provisioning in Vagrant VMs](https://www.vagrantup.com/docs/provisioning/ansible). + +While unit tests are not present in these components made for SURF Research Cloud, there are other tools that can help you: + +- [Molecule deployment tests](https://github.com/ansible/molecule). See [here](https://github.com/UtrechtUniversity/SRC-molecule) for more information on how to utilize Molecule for ResearchCloud items. +- [Ansible testing modules](https://docs.ansible.com/ansible/latest/reference_appendices/test_strategies.html) +- [Ansible Lint](https://ansible-lint.readthedocs.io/en/latest/) +- [Ansible Provisioning in Vagrant VMs](https://www.vagrantup.com/docs/provisioning/ansible). + Try to incorporate as much of TDD into developing playbooks and roles: first determine when your code is succesfull or when it should fail, and then code around those requirements. +CI pipelines for Ansible Lint and Molecule are essential to guarding against the introduction of bugs and maintaining code quality. + ### Specific roles -Reuse the roles defined inside this repository for certain tasks, instead of doing it yourself. Especially for SURF Research Cloud, these roles come in handy: + +The roles in the [uusrc.general collection](./index.md#installing-as-a-collection) contain many roles that faciliate best practices on ResearchCloud, for instance: - Use [runonce](roles/runonce.md) to have a piece of code ran once the first time a user logs in. - Use [desktop_file](roles/desktop_file.md) to create menu and desktop entries. - Use [fact_regular_users](roles/fact_regular_users.md) to gather a list of all users on the system. -- Use [git_clone](roles/git_clone.md) to let users clone a git repository into a environment through arguments. - -### Keep userspace and system-wide seperate -Especially for python-related software: most times, keeping everything separate and private for all users is the best default approach. Let users select their own versions to avoid clashes. +- Use [fact_workspace_info](roles/fact_workspace_info.md) to gather general facts about the workspace, including whether it is a desktop workspace and which [SRAM CO roles](https://utrechtuniversity.github.io/vre-docs/docs/glossary.html#collaboration) are defined. +- Use [nginx_reverse_proxy](roles/nginx_reverse_proxy.md) to easily define reverse proxies and other Nginx locations on top of the SURF Nginx component. +- Use [pipx_install_systemwide](roles/pipx_install_systemwide.md) to avoid installing Python applications using the system Python interpeter (e.g. `/usr/bin/python3`), which might break `pip` dependencies on which the system depends.