doc: final docs and references sweep for 2.0.0

* Contrib needs updates * More clarification on Fedora Server * Update GH issue templates * API and metadata need updates. Change-Id: I5b3187c97aed395c38f9b7f5eab9c699b2955074
redhat-performance · Jun 21, 2024 · 7ed66d7 · 7ed66d7
1 parent 33c4dc5
commit 7ed66d7
Show file tree

Hide file tree

Showing 5 changed files with 32 additions and 27 deletions.
diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md
@@ -3,7 +3,7 @@ name: Bug report
 about: Create a report to help us improve
 
 ---
-* QUADS version (`rpm -qa | grep quads` and/or `quads-cli --version`):
+* QUADS version (`rpm -qa | grep quads` and/or `quads --version`):
 * Python version:
 * Operating System:
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,6 +7,7 @@ Contributing to QUADS
 The QUADS project welcomes contributions from everyone!  Please read the below steps to see how you can contribute to QUADS.
 
 ## Contribution Basics
+  * We do not use the Github Pull Request system.
   * We use [Gerrit](https://review.gerrithub.io/q/project:redhat-performance%252Fquads) for code review
   * You can also find us on IRC at **#quads** on ```irc.libera.chat``` [webchat](https://web.libera.chat/?channels=#quads)
 
@@ -32,17 +33,17 @@ git checkout !$
 podman-compose -f /opt/container/quads/container/container-compose.yml up
 ```
   - This will not background the podman orchestration, so open other terminals to work.
-  - You can now test locally, it's useful to set a bashrc alias for the `bin/quads-cli` commmand
+  - You can now test locally, it's useful to set a bashrc alias for the `/usr/bin/quads` commmand
 
 ```
-echo 'alias quads="podman exec -it quads bin/quads-cli"' >> ~/.bashrc
+echo 'alias quads="podman exec -it quads /usr/bin/quads"' >> ~/.bashrc
 ```
 
 #### MAC OSX Specific
 
   - Make the directory structure for your mapped database data
 ```
-mkdir -p /opt/container/quads/container/{data_db,wiki_db,wordpress_data} 
+mkdir -p /opt/container/quads/container/{data_db,wiki_db,wordpress_data}
 ```
   - Instantiate the podman compose
 ```
@@ -79,7 +80,7 @@ git config --add gitreview.username "vsathir"
 cd quads
 git branch my_change
 git checkout my_change
-vi lib/Quads.py
+vim src/quads/web/app.py
 ```
 
 #### Reloading Environment after Changes
@@ -99,11 +100,11 @@ podman-compose -f container-compose.yml up -d
 * Add a local commit with a meaningful, short title followed by a space and a summary (you can check our [commit history](https://github.com/redhat-performance/quads/commits/latest) for examples.
 * Add a line that relates to a new or existing github issue, e.g. ```fixes: https://github.com/redhat-performance/quads/issues/5``` or ```related-to: https://github.com/redhat-performance/quads/issues/25```
 
-
 ```
 git add quads/api_v2.py
 git commit
 ```
+
 #### Integrate Git Review (First Time Only)
 * Install git-review and run it for first time.
 
@@ -119,12 +120,14 @@ git review -s
 git review
 ```
 
+* If you are adding new functionality or methods you'll need to also include unit tests or CI will get upset.
+
 #### Managing Git Review Patchsets
 
 * If you want to make changes to your patchset you can run the ```git commit --amend``` command.
 
 ```
-vi quads/api_v2.py
+vim /src/quads/quads_api.py
 git commit --amend
 git review
 ```
@@ -143,6 +146,7 @@ git review -d $CHANGEID
 Jenkins CI pipeline currently checks the following for every submitted patchset:
   - shellcheck - checks for common shell syntax errors and issues
   - flake8 - checks Python tools for common syntax errors and issues
+  - [unit tests](https://github.com/redhat-performance/quads/tree/latest/tests)
   - You can trigger CI to run again by commenting on your patchset in gerrit with `retrigger`
 
 #### QUADS CI Architecture

diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@ QUADS (quick and dirty scheduler)
 QUADS automates the future scheduling, end-to-end provisioning and delivery of bare-metal servers and networks.
 
 * Visit the [QUADS blog](https://quads.dev)
-* Please read our [contributing guide](https://github.com/redhat-performance/quads/blob/master/CONTRIBUTING.md) and use [Gerrit Review](https://review.gerrithub.io/q/project:redhat-performance%252Fquads) to submit patches.
+* Please read our [contributing guide](https://github.com/redhat-performance/quads/blob/latest/CONTRIBUTING.md) and use [Gerrit Review](https://review.gerrithub.io/q/project:redhat-performance%252Fquads) to submit patches.
 
 
 ![quads-rpm-build](https://copr.fedorainfracloud.org/coprs/quadsdev/python3-quads/package/quads/status_image/last_build.png)
@@ -126,7 +126,8 @@ QUADS automates the future scheduling, end-to-end provisioning and delivery of b
 ![quadsarchitecture](/image/quads-architecture.png)
 
 ## Requirements
-   - QUADS 2.0+ uses Python3, Flask and Jinja2 with PostgreSQL as the database backend.
+   - Recent [Fedora Server](https://fedoraproject.org/server/download/) for RPM installations
+   - 2 x modest sized VM's for QUADS and the associated Wordpress Wiki component
    - The scheduling functionality can be used standalone, but you'll want a provisioning backend like [Foreman](https://theforeman.org/) to take full advantage of QUADS scheduling, automation and provisioning capabilities.
    - To utilize the automatic wiki/docs generation we use [Wordpress](https://hobo.house/2016/08/30/auto-generating-server-infrastructure-documentation-with-python-wordpress-foreman/) but anything that accepts markdown via an API should work.
    - Switch/VLAN automation is done on Juniper Switches in [Q-in-Q VLANs](http://www.jnpr.net/techpubs/en_US/junos14.1/topics/concept/qinq-tunneling-qfx-series.html), but command sets can easily be extended to support other network switch models.
@@ -232,7 +233,7 @@ sytemctl restart nginx
 
 #### QUADS Wiki
    - The Wiki component for QUADS is currently Wordpress, though in 2.x we'll be moving everything to Flask.
-   - Please use **Red Hat, CentOS Stream or Rocky 8** for the below Wordpress component.
+   - Please use **Red Hat, CentOS Stream or Rocky 8** for the Wordpress component.
    - Wordpress needs to be on it's **own VM/server** as a standalone component.
    - [Wordpress](https://github.com/redhat-performance/ops-tools/tree/master/ansible/wiki-wordpress-nginx-mariadb) provides a place to automate documentation and inventory/server status via the Wordpress Python RPC API.
 
@@ -864,7 +865,7 @@ Removed: {'host': 'f03-h30-000-r720xd.rdu2.example.com'}
 * Before using this, make sure it's not easier to simply use `--shrink` or `--extend` and sub-commands across the entire cloud/environments or even per-host first.
 
 ```bash
-quads --mod-schedule --host host01.example.com --mod-schedule --schedule-id 31 --schedule-start "2023-05-22 22:00" --schedule-end "2023-06-22 22:00"
+quads --mod-schedule --host host01.example.com --mod-schedule --schedule-id 31 --schedule-start "2023-05-22 22 :00" --schedule-end "2023-06-22 22:00"
 ```
 
 #### Modifying a Host Schedule across a large set of hosts

diff --git a/docs/quads-api.md b/docs/quads-api.md
@@ -108,8 +108,8 @@ curl -X POST -u $USERNAME:$PASSWORD -H 'accept: application/json' 'http://localh
   * You can combine one of many POST query types with multiple POST metadata objects.
   * There is limited support for data modification via POST as well documented below.
   * Valid POST URI queries
-    - ```/api/v3/hosts```        Same as `quads-cli --define-host`, used for defining a new host.
-    - ```/api/v3/clouds```       Same as `quads-cli --define-cloud` for creating/updating a cloud environment.
+    - ```/api/v3/hosts```        Same as `quads --define-host`, used for defining a new host.
+    - ```/api/v3/clouds```       Same as `quads --define-cloud` for creating/updating a cloud environment.
     - ```/api/v3/schedules```    AKA _add host schedule_ used for adding a new host schedule.
     - ```/api/v3/interfaces```   Add an interface to a QUADS-managed host
 

diff --git a/docs/quads-host-metadata-search.md b/docs/quads-host-metadata-search.md
@@ -27,15 +27,15 @@ In QUADS `1.1.4` and above we've implemented a metadata model in MongoDB that ca
   * To generate a YAML metadata file for importing QUADS-managed hosts you can use this command:
 
 ```
-for h in $(quads-cli --ls-hosts) ; do echo "- name: $h" ; echo "  model: $(echo $h | awk -F. '{ print $1 }' | awk -F- '{ print $NF }' | tr a-z A-Z)" ; done > /tmp/hosts_metadata.yml
+for h in $(quads --ls-hosts) ; do echo "- name: $h" ; echo "  model: $(echo $h | awk -F. '{ print $1 }' | awk -F- '{ print $NF }' | tr a-z A-Z)" ; done > /tmp/hosts_metadata.yml
 ```
 
 ### Importing Host Metadata
 
   * To import host metadata from a file:
 
 ```
-quads-cli --define-host-details --metadata /tmp/hosts_metadata.yml
+quads --define-host-details --metadata /tmp/hosts_metadata.yml
 ```
 
   * Doing this again or modifying your `hosts_metadata.yml` file and re-importing will overwrite all values or remove ones that might have been removed from the QUADS database.
@@ -45,7 +45,7 @@ quads-cli --define-host-details --metadata /tmp/hosts_metadata.yml
   * The file provided should be a new file, or overwrite an existing one and the path should be somewhere on the filesystem.
 
 ```
-quads-cli --export-host-details /tmp/my_host_data.yml
+quads --export-host-details /tmp/my_host_data.yml
 ```
 
 ## Querying Host Information
@@ -79,31 +79,31 @@ quads-cli --export-host-details /tmp/my_host_data.yml
   * Search for systems with disk type NVMe, with a size of 2TB or more and available between `2020-07-20 17:00` and `2020-07-22 13:00`
 
 ```
-quads-cli --ls-available --schedule-start "2020-07-20 17:00" --schedule-end "2020-07-22 13:00" --filter "disks.disk_type==nvme,disks.size_gb>=2000"
+quads --ls-available --schedule-start "2020-07-20 17:00" --schedule-end "2020-07-22 13:00" --filter "disks.disk_type==nvme,disks.size_gb>=2000"
 ```
 
   * Search for systems with SATA disks available from `2020-07-20 17:00` until `2020-07-22 13:00`
 
 ```
-quads-cli --ls-available --schedule-start "2020-07-20 17:00" --schedule-end "2020-07-22 13:00" --filter "disks.disk_type==sata"
+quads --ls-available --schedule-start "2020-07-20 17:00" --schedule-end "2020-07-22 13:00" --filter "disks.disk_type==sata"
 ```
 
   * Search for systems of model type `1029U-TRTP` available from `2020-07-20 17:00` until `2020-07-22 13:00`
 
 ```
-quads-cli --ls-available --schedule-start "2020-07-20 17:00" --schedule-end "2020-07-22 13:00" --filter "model==1029U-TRTP"
+quads --ls-available --schedule-start "2020-07-20 17:00" --schedule-end "2020-07-22 13:00" --filter "model==1029U-TRTP"
 ```
 
   * Search for systems with **two NVMe** disks **and** disk size of **more than** 2TB, available from `2020-07-20 17:00` until `2020-07-22 13:00`
 
 ```
-quads-cli --ls-available --schedule-start "2020-07-20 17:00" --schedule-end "2020-07-22 13:00" --filter "disks.disk_type==nvme,disks.count>2, disks.size_gb<2000"
+quads --ls-available --schedule-start "2020-07-20 17:00" --schedule-end "2020-07-22 13:00" --filter "disks.disk_type==nvme,disks.count>2, disks.size_gb<2000"
 ```
 
   * Search all systems by model and number of interfaces.
 
 ```
-quads-cli --ls-hosts --filter "model==FC640,interfaces__size==5"
+quads --ls-hosts --filter "model==FC640,interfaces__size==5"
 ```
 
 #### Example Network Filter Searches
@@ -112,21 +112,21 @@ quads-cli --ls-hosts --filter "model==FC640,interfaces__size==5"
   * This is useful for finding what host has what MAC Address.
 
 ```
-quads-cli --ls-hosts --filter "interfaces.mac_address==ac:1f:6b:2d:19:48"
+quads --ls-hosts --filter "interfaces.mac_address==ac:1f:6b:2d:19:48"
 ```
 
   * Find hosts by switch IP address.
   * Shows all hosts connected to a particular switch
 
 ```
-quads-cli --ls-host --filter "interfaces.ip_address==10.1.34.216"
+quads --ls-host --filter "interfaces.ip_address==10.1.34.216"
 ```
 
   * Find hosts by physical switchport
   * Shows all hosts that have a specific physical switchport name
 
 ```
-quads-cli --ls-host --filter "interfaces.switch_port==et-0/0/7:1"
+quads --ls-host --filter "interfaces.switch_port==et-0/0/7:1"
 ```
 
 ##### Combined Network Search Example
@@ -135,7 +135,7 @@ quads-cli --ls-host --filter "interfaces.switch_port==et-0/0/7:1"
   * Example: Search for a host by physical switchport **and** switch IP address.
 
 ```
-quads-cli --ls-hosts --filter "interfaces.ip_address==10.1.34.216,interfaces.switch_port==et-0/0/7:1"
+quads --ls-hosts --filter "interfaces.ip_address==10.1.34.216,interfaces.switch_port==et-0/0/7:1"
 ```
 
 ## Querying Host Status
@@ -147,11 +147,11 @@ quads-cli --ls-hosts --filter "interfaces.ip_address==10.1.34.216,interfaces.swi
   * List all systems by retirement (decomission) status.
 
 ```
-quads-cli --ls-hosts --filter "retired==True"
+quads --ls-hosts --filter "retired==True"
 ```
 
   * List retired hosts and filter by model
 
 ```
-quads-cli --ls-hosts --filter "retired==True,model==1029P"
+quads --ls-hosts --filter "retired==True,model==1029P"
 ```