From 3efb67e110870db817ef31c5384f91d8c8c5eb9e Mon Sep 17 00:00:00 2001
From: ashmrtn <3891298+ashmrtn@users.noreply.github.com>
Date: Mon, 17 Jul 2023 23:20:42 -0700
Subject: [PATCH] First pass at documentation for maintenance (#3830)

Assumes the addition of `--user` and `--hostname` flags

Also unhides the maintenance command and mode flag

---

#### Does this PR need a docs update or release note?

- [ ] :white_check_mark: Yes, it's included
- [ ] :clock1: Yes, but in a later PR
- [x] :no_entry: No

#### Type of change

- [ ] :sunflower: Feature
- [ ] :bug: Bugfix
- [x] :world_map: Documentation
- [ ] :robot: Supportability/Tests
- [ ] :computer: CI/Deployment
- [ ] :broom: Tech Debt/Cleanup

#### Issue(s)

* #3569

#### Test Plan

- [x] :muscle: Manual
- [ ] :zap: Unit test
- [ ] :green_heart: E2E
---
 src/cli/flags/maintenance.go         |  9 ++----
 src/cli/repo/repo.go                 |  6 +---
 website/docs/setup/maintenance.md    | 41 ++++++++++++++++++++++++++++
 website/sidebars.js                  |  5 ++--
 website/styles/Vocab/Base/accept.txt |  4 ++-
 5 files changed, 51 insertions(+), 14 deletions(-)
 create mode 100644 website/docs/setup/maintenance.md

diff --git a/src/cli/flags/maintenance.go b/src/cli/flags/maintenance.go
index f1ae253ae..e75b7c846 100644
--- a/src/cli/flags/maintenance.go
+++ b/src/cli/flags/maintenance.go
@@ -26,12 +26,9 @@ func AddMaintenanceModeFlag(cmd *cobra.Command) {
 		&MaintenanceModeFV,
 		MaintenanceModeFN,
 		repository.CompleteMaintenance.String(),
-		"Type of maintenance operation to run. Pass '"+
-			repository.MetadataMaintenance.String()+"' to run a faster maintenance "+
-			"that does minimal clean-up and optimization. Pass '"+
-			repository.CompleteMaintenance.String()+"' to fully compact existing "+
-			"data and delete unused data.")
-	cobra.CheckErr(fs.MarkHidden(MaintenanceModeFN))
+		"Type of maintenance operation to run ('"+
+			repository.MetadataMaintenance.String()+"' | '"+
+			repository.CompleteMaintenance.String()+"' )")
 }
 
 func AddForceMaintenanceFlag(cmd *cobra.Command) {
diff --git a/src/cli/repo/repo.go b/src/cli/repo/repo.go
index d9822c33e..21ff2d11e 100644
--- a/src/cli/repo/repo.go
+++ b/src/cli/repo/repo.go
@@ -38,12 +38,8 @@ func AddCommands(cmd *cobra.Command) {
 	cmd.AddCommand(repoCmd)
 	repoCmd.AddCommand(initCmd)
 	repoCmd.AddCommand(connectCmd)
+	repoCmd.AddCommand(maintenanceCmd)
 
-	utils.AddCommand(
-		repoCmd,
-		maintenanceCmd,
-		utils.HideCommand(),
-		utils.MarkPreReleaseCommand())
 	flags.AddMaintenanceModeFlag(maintenanceCmd)
 	flags.AddForceMaintenanceFlag(maintenanceCmd)
 	flags.AddMaintenanceUserFlag(maintenanceCmd)
diff --git a/website/docs/setup/maintenance.md b/website/docs/setup/maintenance.md
new file mode 100644
index 000000000..b3263f186
--- /dev/null
+++ b/website/docs/setup/maintenance.md
@@ -0,0 +1,41 @@
+---
+description: "Repository maintenance."
+---
+
+# Repository maintenance
+
+Repository maintenance helps optimize the Corso repository as backups are created and possibly deleted by the user.  
+Maintenance can also free up space by removing data no longer referenced by any backups from the repository.
+
+It's safe to run maintenance concurrently with backup, restore, and backup deletion operations. However, it's not safe  
+to run maintenance operations concurrently on the same repository. Corso uses file locks and the idea of a repository  
+owner to try to detect concurrent maintenance operations.
+
+## Repository owner
+
+The repository owner is set to the user and hostname of the machine that runs maintenance on the repo the first time.  
+
+If the user and hostname of the machine running maintenance can change, use either the `--force` flag or the `--user`  
+and `--host` flags.
+
+The `--force` flag updates the repository owner and runs maintenance.
+
+The `--user` and `--host` flags act as if the given user/hostname owns the repository for the maintenance operation  
+but doesn't update repo owner info.
+
+*If any of these flags are passed the user must make sure no concurrent maintenance operations run on the same  
+repository. Concurrent maintenance operations a repository may result in data loss.*
+
+## Maintenance types
+
+Corso allows for two different types of maintenance: `metadata` and `complete`.
+
+Metadata maintenance runs quickly and optimizes indexing data. Complete maintenance takes more time but compacts data  
+in backups and removes unreferenced data from the repository.
+
+As Corso allows concurrent backups during maintenance, running complete maintenance immediately after deleting a  
+backup may not result in a reduction of objects in the storage service Corso is backing up to.  
+
+Deletion of old objects in the storage service depends on both wall-clock time and running maintenance.
+
+Later maintenance runs on the repository will remove the data.
diff --git a/website/sidebars.js b/website/sidebars.js
index e1d5ddae8..d15428e14 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -27,7 +27,8 @@ const sidebars = {
         'setup/configuration',
         'setup/repos',
         'setup/fault-tolerance',
-        'setup/restore-options'
+        'setup/restore-options',
+        'setup/maintenance'
       ],
     },
     {
@@ -112,4 +113,4 @@ const sidebars = {
   ],
 };
 
-module.exports = sidebars;
\ No newline at end of file
+module.exports = sidebars;
diff --git a/website/styles/Vocab/Base/accept.txt b/website/styles/Vocab/Base/accept.txt
index 4ed3b41bf..421ef5ca0 100644
--- a/website/styles/Vocab/Base/accept.txt
+++ b/website/styles/Vocab/Base/accept.txt
@@ -57,4 +57,6 @@ exfiltrate
 deduplicating
 subtree
 subtrees
-anonymized
\ No newline at end of file
+anonymized
+unreferenced
+hostname