docs: document changes to update_manager

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>

docs/api_changes.md

@@ -1,5 +1,22 @@
 ##
-This document keeps a record of all changes to Moonraker's web APIs.
+This document keeps a record of notable changes to Moonraker's Web API.
+
+### July 18th 2023
+- Moonraker API Version 1.3.0
+- Added [Spoolman](web_api.md#spoolman-apis) APIs.
+- Added [Rollback](web_api.md#rollback-to-the-previous-version) API to
+  the `update_manager`
+- The `update_manager` status response has new fields for items of the
+  `git_repo` and `web` types:
+  - `recovery_url`: Url of the repo a "hard" recovery will fetch from
+  - `rollback_version`: Version the extension will revert to when a rollback
+    is requested
+  - `warnings`: An array of strings containing various warnings detected
+    during repo init.  Some warnings may explain an invalid state while
+    others may alert users to potential issues, such as a `git_repo` remote
+    url not matching the expected (ie: configured) url.
+  - Additionally, the `need_channel_update` field has been removed as the method
+    changing channels is done exclusively in the configuration.
 
 ### February 20th 2023
 - The following new endpoints are available when at least one `[sensor]`

docs/changelog.md

@@ -17,6 +17,8 @@ The format is based on [Keep a Changelog].
 - **zeroconf**: Added support for UPnP/SSDP Discovery.
 - **spoolman**: Added integration to the
   [Spoolman](https://github.com/Donkie/Spoolman) filament manager.
+- **update_manager**: Added support for update rollbacks
+- **update_manager**: Added support for stable `git_repo` updates
 
 ### Fixed
 
@@ -47,7 +49,7 @@ The format is based on [Keep a Changelog].
   configurations should use the `virtualenv` option.
 - **update_manager**: The `install_script` option for the `git_repo` has been
   deprecated, new configurations should use the `system_dependencies` option.
-- **API**: The `update_manager` APIs that return status report additional fields.
+- **update_manager**: APIs that return status report additional fields.
   See the [API Documentation](./web_api.md#get-update-status) for details.
 
 ## [0.8.0] - 2023-02-23

docs/user_changes.md

@@ -1,6 +1,18 @@
 ##
-This file will track changes that require user intervention,
+This file tracks configuration changes and deprecations.  Additionally
-such as a configuration change or a reinstallation.
+changest to Moonraker that require user intervention will be tracked
+here.
+
+### July 18th 2023
+- The following changes have been made to `[update_manager <name>]`
+  extensions of the `git_repo` type:
+  - The `env` option has been deprecated.  New configurations should
+    use the `virtualenv` option in its place.
+  - The `install_script` option has been deprecated. New configurations
+    should use the `system_dependencies` option to specify system package
+    dependencies.
+- Configuration options for `[spoolman]` have been added
+- Configuration options for `[sensor]` have been added
 
 ### Februrary 8th 2023
 - The `provider` option in the `[machine]` section no longer accepts

docs/web_api.md

@@ -4144,7 +4144,6 @@ and `fluidd` are present as clients configured in `moonraker.conf`
         "moonraker": {
             "channel": "dev",
             "debug_enabled": true,
-            "need_channel_update": false,
             "is_valid": true,
             "configured_type": "git_repo",
             "corrupt": false,
@@ -4156,6 +4155,7 @@ and `fluidd` are present as clients configured in `moonraker.conf`
             "repo_name": "moonraker",
             "version": "v0.7.1-364",
             "remote_version": "v0.7.1-364",
+            "rollback_version": "v0.7.1-360",
             "current_hash": "ecfad5cff15fff1d82cb9bdc64d6b548ed53dfaf",
             "remote_hash": "ecfad5cff15fff1d82cb9bdc64d6b548ed53dfaf",
             "is_dirty": false,
@@ -4173,6 +4173,7 @@ and `fluidd` are present as clients configured in `moonraker.conf`
             "owner": "mainsail-crew",
             "version": "v2.1.1",
             "remote_version": "v2.1.1",
+            "rollback_version": "v2.0.0",
             "configured_type": "web",
             "channel": "stable",
             "info_tags": [
@@ -4187,6 +4188,7 @@ and `fluidd` are present as clients configured in `moonraker.conf`
             "owner": "fluidd-core",
             "version": "v1.16.2",
             "remote_version": "v1.16.2",
+            "rollback_version": "v1.15.0",
             "configured_type": "web",
             "channel": "beta",
             "info_tags": [],
@@ -4196,7 +4198,6 @@ and `fluidd` are present as clients configured in `moonraker.conf`
         "klipper": {
             "channel": "dev",
             "debug_enabled": true,
-            "need_channel_update": false,
             "is_valid": true,
             "configured_type": "git_repo",
             "corrupt": false,
@@ -4208,6 +4209,7 @@ and `fluidd` are present as clients configured in `moonraker.conf`
             "repo_name": "klipper",
             "version": "v0.10.0-1",
             "remote_version": "v0.10.0-41",
+            "rollback_version": "v0.9.1-340",
             "current_hash": "4c8d24ae03eadf3fc5a28efb1209ce810251d02d",
             "remote_hash": "e3cbe7ea3663a8cd10207a9aecc4e5458aeb1f1f",
             "is_dirty": false,
@@ -4252,23 +4254,18 @@ Below is an explanation for each field:
 - `github_limit_reset_time`:  the time when the rate limit will reset,
   reported as seconds since the epoch (aka Unix Time).
 
-The `moonraker`, `klipper` packages, along with and clients configured
+Extensions configured with the `git_repo` type will contain the following
-as applications have the following fields:
+fields:
 
 - `configured_type`: the application type configured by the user
 - `detected_type`:  the application type as detected by Moonraker.
 - `channel`:  the currently configured update channel.  For Moonraker
   and Klipper this is set in the `[update_manager]` configuration.
   For clients the channel is determined by the configured type
-- `need_channel_update`: This will be set to `true` if Moonraker has
+- `pristine`: Indicates that there are no modified files or untracked
-  detected that a channel swap is necessary (ie: the configured type does
+  source files in a `git_repo`.  A repo with untracked files can still
-  not match the detected type). The channel swap will be performed on the
+  be updated, however a repo with modified files (ie: `dirty`) cannot
-  next update.
+  be updated.
-- `pristine`: For `zip` and `zip_beta` types this is set to `true` if an
-  applications source checksum matches the one generated  when the app was
-  built.  This value will be set to the opposite of "dirty" for git repos.
-  Note that a zip application can still be updated if the repo is not
-  pristine.
 - `owner`: the owner of the repo / application
 - `branch`: the name of the current git branch.  This should typically
     be "master".
@@ -4276,26 +4273,22 @@ as applications have the following fields:
     "origin".
 - `version`:  abbreviated version of the current repo on disk
 - `remote_version`: abbreviated version of the latest available update
+- `rollback_version`: version the repo will revert to when a rollback is
+   requested
 - `full_version_string`:  The complete version string of the current repo.
 - `current_hash`: hash of the most recent commit on disk
 - `remote_hash`: hash of the most recent commit pushed to the remote
-- `is_valid`: true if installation is a valid git repo on the master branch
+- `is_valid`: true if the `git_repo` is valid and can be updated.
-    and an "origin" set to the official remote.  For `zip` and `zip_beta`
-    types this will report false if Moonraker is unable to fetch the
-    current repo state from GitHub.
 - `corrupt`: Indicates that the git repo has been corrupted.  When a repo
   is in this state it a hard recovery (ie: re-cloning the repo) is necessary.
   Note that the most common cause of repo corruption is removing power from
   the host machine without safely shutting down.  Damaged storage can also
   lead to repo corruption.
-- `is_dirty`: true if the repo has been modified.  This will always be false
+- `is_dirty`: true if a `git_repo` has modified files.  A dirty repo cannot
-  for `zip` and `zip_beta` types.
+  be updated.
-- `detached`: true if the repo is currently in a detached state.  For `zip`
+- `detached`: true if the `git_repo` is currently in a detached state.
-  and `zip_beta` types it is considered detached if the local release info
+- `debug_enabled`: True when debug flag has been set via the command line.
-  does not match what is present on the remote.
+  When debug is enabled Moonraker will allow detached updates.
-- `debug_enabled`: True when `enable_repo_debug` has been configured.  This
-    will bypass repo validation allowing detached updates, and updates from
-    a remote/branch other than than the primary (typically origin/master).
 - `commits_behind`: A list of commits behind.  Up to 30 "untagged" commits
   will be reported.  Moonraker checks the last 100 commits for tags, any
   commits beyond the last 30 with a tag will also be reported.
@@ -4316,9 +4309,9 @@ as applications have the following fields:
 - `warnings`:  An array of strings that describe warnings detected during
   repo init.  These warnings describe potential issues, such as a mismatch
   between the detected remote and the configured remote.  If the `is_valid`
-  field reports `False` then the warnings will contain additional context.
+  field reports `false` then the warnings will contain additional context.
 
-Web clients have the following fields:
+Extensions configured with the `web` type will contain the following fields:
 
 - `channel`: channel to fetch updates from
 - `configured_type`: will be `web`
@@ -4326,6 +4319,8 @@ Web clients have the following fields:
 - `owner`: the owner of the client
 - `version`:  version of the installed client.
 - `remote_version`:  version of the latest release published to GitHub
+- `rollback_version`: version the client will revert to when a rollback is
+   requested
 - `info_tags`: These are tags defined in the `[update_manager client_name]`
   configuration for each client. Client developers my define what tags,
   if any, users will configure.  They can choose to use those tags to display
@@ -4338,7 +4333,7 @@ Web clients have the following fields:
   field reports `False` then the warnings will contain additional context.
 
 
-The `system` package has the following fields:
+The `system` object contains the following fields:
 
 - `package_count`: the number of system packages available for update
 - `package_list`: an array containing the names of packages available
@@ -4545,6 +4540,31 @@ Returns:
 
 `ok` when complete
 
+### Rollback to the previous version
+
+HTTP request:
+
+```http
+POST /machine/update/rollback?name=moonraker
+```
+
+JSON-RPC request:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "machine.update.rollback",
+    "params": {
+        "name": "moonraker"
+    },
+    "id": 4564
+}
+```
+
+Returns:
+
+`ok` when complete
+
 ### Power APIs
 The APIs below are available when the `[power]` component has been configured.