From fe2516b9ba1e718197e67ab943f78d7e74557cdd Mon Sep 17 00:00:00 2001 From: Georgi Matev Date: Fri, 30 Sep 2022 03:31:58 -0400 Subject: [PATCH] Fix all Vale [error] level lint issues and all markdownlint issues (#997) ## Description * fixes all `markdownlint` issues, includeing autogenerated docs * fixes [error] level Vale problems * ## Type of change - [ ] :sunflower: Feature - [x] :bug: Bugfix - [x] :world_map: Documentation - [ ] :robot: Test - [ ] :computer: CI/Deployment - [x] :hamster: Trivial/Minor ## Issue(s) ## Test Plan - [x] :muscle: Manual - [ ] :zap: Unit test - [ ] :green_heart: E2E --- docs/.vale.ini | 7 ++++++- docs/README.md | 2 +- .../docs/cli/corso_backup_details_exchange.md | 2 +- docs/docs/cli/corso_restore_exchange.md | 2 +- docs/docs/configuration/concepts.md | 2 +- docs/docs/configuration/m365_access.md | 16 ++++++++------- docs/docs/configuration/repos.md | 2 ++ docs/docs/developers/architecture.md | 2 ++ docs/docs/developers/build.md | 2 ++ docs/docs/developers/linters.md | 20 +++++++++++-------- docs/docs/intro.md | 4 ++-- docs/docs/tutorial.md | 7 +++++-- docs/styles/Microsoft/Acronyms.yml | 1 + docs/styles/Vocab/Base/accept.txt | 8 ++++++-- src/cli/backup/exchange.go | 2 +- src/cli/restore/exchange.go | 2 +- 16 files changed, 53 insertions(+), 28 deletions(-) diff --git a/docs/.vale.ini b/docs/.vale.ini index 1b63e99df..e81774ef4 100644 --- a/docs/.vale.ini +++ b/docs/.vale.ini @@ -14,8 +14,13 @@ write-good.E-Prime = NO [*.md] BasedOnStyles = Vale, Microsoft, proselint, write-good, alex +# Ignore the following blocks: +# - MDX code blocks - e.g. {mdx_code} +# - imports - e.g. import from ; +# - corso command line examples first line in a bash code block starting with `corso` BlockIgnores = (\{\#.*?\}), \ - (import.*?from.*?;) + (import.*?from.*?;),\ + (?s) (```bash.*?corso.*?$) [*.json] BasedOnStyles = Vale diff --git a/docs/README.md b/docs/README.md index cac8b4ce2..c386eeff8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,7 +30,7 @@ This command starts a local development server within the Docker container and w make genclidocs ``` -Corso's CLI documents are auto-generated. This command explicitly triggers generating these docs. This step will happen +Corso's CLI documents are auto generated. This command explicitly triggers generating these docs. This step will happen automatically for the other commands where this is relevant. ## Building static documentation diff --git a/docs/docs/cli/corso_backup_details_exchange.md b/docs/docs/cli/corso_backup_details_exchange.md index bd3f66fc1..935e78510 100644 --- a/docs/docs/cli/corso_backup_details_exchange.md +++ b/docs/docs/cli/corso_backup_details_exchange.md @@ -27,7 +27,7 @@ corso backup details exchange [flags] |`--event`||`[]`|Select backup details by event ID; accepts * to select all events| |`--event-calendar`||`[]`|Select backup details by event calendar ID; accepts * to select all events| |`--event-organizer`|||Select backup details where the event organizer user id contains this value| -|`--event-recurs`|||Select backup details if the event recurs. Use --event-recurs false to select where the event does not recur.| +|`--event-recurs`|||Select backup details if the event recurs. Use `--event-recurs` false to select non-recurring events| |`--event-starts-after`|||Select backup details where the event starts after this datetime| |`--event-starts-before`|||Select backup details where the event starts before this datetime| |`--event-subject`|||Select backup details where the event subject contains this value| diff --git a/docs/docs/cli/corso_restore_exchange.md b/docs/docs/cli/corso_restore_exchange.md index 8960b310e..5684f33fb 100644 --- a/docs/docs/cli/corso_restore_exchange.md +++ b/docs/docs/cli/corso_restore_exchange.md @@ -27,7 +27,7 @@ corso restore exchange [flags] |`--event`||`[]`|Restore events by ID; accepts * to select all events| |`--event-calendar`||`[]`|Restore events by calendar ID; accepts * to select all event calendars| |`--event-organizer`|||Restore events where the event organizer user id contains this value| -|`--event-recurs`|||Restore events if the event recurs. Use --event-recurs false to select where the event does not recur.| +|`--event-recurs`|||Restore events if the event recurs. Use `--event-recurs false` to select non-recurring events| |`--event-starts-after`|||Restore events where the event starts after this datetime| |`--event-starts-before`|||Restore events where the event starts before this datetime| |`--event-subject`|||Restore events where the event subject contains this value| diff --git a/docs/docs/configuration/concepts.md b/docs/docs/configuration/concepts.md index b13843a58..5bb55432c 100644 --- a/docs/docs/configuration/concepts.md +++ b/docs/docs/configuration/concepts.md @@ -24,4 +24,4 @@ application to connect to your *M365 tenant* and transfer data during backup and *M365 Services* data. See [Repositories](/configuration/repos) for more information. * **Backup** is a copy of your *M365 Services* data to be used for restores in case of deletion, loss, or corruption of the -original data. Corso performs backups incrementall, and each backup only captures data that has changed between backup iterations. +original data. Corso performs backups incrementally, and each backup only captures data that has changed between backup iterations. diff --git a/docs/docs/configuration/m365_access.md b/docs/docs/configuration/m365_access.md index 0fa5f52cc..377188cc3 100644 --- a/docs/docs/configuration/m365_access.md +++ b/docs/docs/configuration/m365_access.md @@ -16,10 +16,10 @@ The following steps outline a simplified procedure for creating an Azure Ad appl 1. **Create a new application** - Select **Azure Active Directory → App Registrations → New Registration** - + Select **Azure Active Directory → App Registrations → New Registration** + -2. **Configure basic settings** +1. **Configure basic settings** * Give the application a name * Select **Accounts in this organizational directory only** @@ -27,7 +27,7 @@ The following steps outline a simplified procedure for creating an Azure Ad appl
-3. **Configure required permissions** +1. **Configure required permissions** Select **App Permission** from the app management panel. @@ -35,14 +35,16 @@ The following steps outline a simplified procedure for creating an Azure Ad appl The required permissions are as follows: - **TODO: Complete list of permissions** + + TODO: Complete list of permissions + | API / Permissions Name | Type | - |--|--| + |:--|:--| | Permission 1 | Application | | Permission 2 | Delegated | -4. **Grant admin consent** +1. **Grant admin consent** diff --git a/docs/docs/configuration/repos.md b/docs/docs/configuration/repos.md index e21cb53b6..341ea79b1 100644 --- a/docs/docs/configuration/repos.md +++ b/docs/docs/configuration/repos.md @@ -24,7 +24,9 @@ Before setting you your Corso S3 repository, the following prerequisites must be * S3 bucket for the repository already exists. Corso won't create it for you. * You have access to credentials for a user or an IAM role that represent the following permissions + **TODO: Verify if these permissions are correct? What about multi-part upload permissions?** + ```json { diff --git a/docs/docs/developers/architecture.md b/docs/docs/developers/architecture.md index 7fb2ee7ae..cc98ae573 100644 --- a/docs/docs/developers/architecture.md +++ b/docs/docs/developers/architecture.md @@ -1,3 +1,5 @@ # Architecture + TODO + \ No newline at end of file diff --git a/docs/docs/developers/build.md b/docs/docs/developers/build.md index c42f179fb..79bdfc55d 100644 --- a/docs/docs/developers/build.md +++ b/docs/docs/developers/build.md @@ -1,3 +1,5 @@ # Build from source + TODO + diff --git a/docs/docs/developers/linters.md b/docs/docs/developers/linters.md index 09d8a5798..9cf192ff1 100644 --- a/docs/docs/developers/linters.md +++ b/docs/docs/developers/linters.md @@ -26,7 +26,7 @@ installed. There’s a `Makefile` in the corso/src that will automatically check if the proper golangci-lint version is installed and run it. This make rule can be run with `make lint`. If golangci-lint isn't installed locally or the wrong version -is present it will tell you what version it expects and provide a link to the +is present it will tell you what version it expects along with a link to the installation page. ### Running manually @@ -36,8 +36,8 @@ directory. This will automatically use corso's `.golangci.yml` configuration. ## Adding exceptions for lint errors -Sometimes the linter will report an issue but it's not something that can or -should be fixed. In those cases there are two ways to add a linter exception: +Sometimes the linter will report an issue but it's not something that you can or +should fix. In those cases there are two ways to add a linter exception: ### Single exception via comment @@ -68,10 +68,12 @@ Some of the enabled linters, like `wsl`, are picky about how code is arranged. This section provides some tips on how to organize code to reduce lint errors. ### `wsl` + `wsl` is a linter that requires blank lines in parts of the code. It helps make -the codebase more uniform and ensures the code doesn't feel too compact. +the codebase uniform and ensures the code doesn't feel too compact. #### Short-assignments versus var declarations + Go allows declaring and assigning to a variable with either short-assignments (`x := 42`) or var assignments (`var x = 42`). `wsl` doesn't allow grouping these two types of variable declarations together. To work around this, @@ -97,6 +99,7 @@ var ( ``` #### Post-increment and assignments + `wsl` doesn't allow statements before an assignment without a blank line separating the two. Post-increment operators (e.x. `x++`) count as statements instead of assignments and may cause `wsl` to report an error. You can avoid @@ -118,6 +121,7 @@ x++ ``` #### Functions using recently assigned values + `wsl` allows functions immediately after assignments, but only if the function uses the assigned value. This requires an ordering for assignments and function calls. @@ -150,6 +154,7 @@ foo(a, b) ``` #### Function calls and checking returned error values + One of the other linters expects error checks to follow assignments to the error variable without blank lines separating the two. One the other hand, `wsl` has requirements about what statements can be mixed with assignments. To work @@ -180,8 +185,7 @@ if err != nil { ## Common problem linters Some linter messages aren't clear about what the issue is. Here's common -cryptic messages we've dealt with in the past and how you can fix the problems -the linters flag. +cryptic messages how you can fix the problems the linters flag. Each subsection also includes the version of golangci-lint it applies to and the linter in question. @@ -190,8 +194,8 @@ linter in question. This applies to golangci-lint v1.45.2 for the `gci` linter and is due to an import ordering issue. It occurs because imports in the file aren't grouped according to the import rules for Corso. Corso code should have three distinct import -groups: system imports, third party imports, and imports of other Corso packaged; -see the example below. Typically the cause of a `gci` lint error is a Corso import in the +groups: system imports, third party imports, and imports of other Corso packaged +(see the example below). Typically the cause of a `gci` lint error is a Corso import in the block for third party libraries. ```go diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 86ab5c54f..d74f82adc 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -12,5 +12,5 @@ beyond M365, will expand based on the interest and needs of the community. ## Getting started -Follow the instructions in the [Installation](/install) and [Initial Configuration](/configuration/concepts) sections to setup -Corso and get it ready for first use. You can then go through the [Tutorial](/tutorial) section to see it in action. +Follow the instructions in the [Installation](/install) and [Initial Configuration](/configuration/concepts) sections to +setup Corso and get it ready for first use. You can then go through the [Tutorial](/tutorial) section to see it in action. diff --git a/docs/docs/tutorial.md b/docs/docs/tutorial.md index f0a638c77..f8975621e 100644 --- a/docs/docs/tutorial.md +++ b/docs/docs/tutorial.md @@ -27,7 +27,9 @@ $ docker run -e CORSO_PASSPHRASE \ Your first backup may take some time if your mailbox is large. ::: + **TODO:** Update ^^^ after the finalization of Corso output from operations. + ## Restore an email @@ -42,8 +44,9 @@ $ docker run -e CORSO_PASSPHRASE \ -v ~/.corso/logs:/app/logs corso/corso:latest \ backup list exchange --user ``` - + **TODO:** Update ^^^ after the finalization of Corso output from operations. + Select one of the available backups and search through its contents. @@ -58,7 +61,7 @@ $ docker run -e CORSO_PASSPHRASE \ --email-subject ``` -The output from the executed command above should display a list of any matching emails. Note the ID +The output from the command above should display a list of any matching emails. Note the ID of the one to use for testing restore. When you are ready to restore, use the following command: diff --git a/docs/styles/Microsoft/Acronyms.yml b/docs/styles/Microsoft/Acronyms.yml index 366edbfe4..a3a8a0661 100644 --- a/docs/styles/Microsoft/Acronyms.yml +++ b/docs/styles/Microsoft/Acronyms.yml @@ -65,3 +65,4 @@ exceptions: - XSS - YAML - ZIP + - HOME diff --git a/docs/styles/Vocab/Base/accept.txt b/docs/styles/Vocab/Base/accept.txt index dbae1d170..ebc30b679 100644 --- a/docs/styles/Vocab/Base/accept.txt +++ b/docs/styles/Vocab/Base/accept.txt @@ -1,4 +1,8 @@ -Corso +[Cc]orso Docusaurus -config +[Cc]onfig Config +datetime +(?i)OneDrive +[Rr]epo +env \ No newline at end of file diff --git a/src/cli/backup/exchange.go b/src/cli/backup/exchange.go index 25fc4cbb8..791736283 100644 --- a/src/cli/backup/exchange.go +++ b/src/cli/backup/exchange.go @@ -149,7 +149,7 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command { fs.StringVar( &eventRecurs, "event-recurs", "", - "Select backup details if the event recurs. Use --event-recurs false to select where the event does not recur.") + "Select backup details if the event recurs. Use `--event-recurs` false to select non-recurring events") fs.StringVar( &eventStartsAfter, "event-starts-after", "", diff --git a/src/cli/restore/exchange.go b/src/cli/restore/exchange.go index 3e65f94b4..b691eb4a9 100644 --- a/src/cli/restore/exchange.go +++ b/src/cli/restore/exchange.go @@ -108,7 +108,7 @@ func addExchangeCommands(parent *cobra.Command) *cobra.Command { fs.StringVar( &eventRecurs, "event-recurs", "", - "Restore events if the event recurs. Use --event-recurs false to select where the event does not recur.") + "Restore events if the event recurs. Use `--event-recurs false` to select non-recurring events") fs.StringVar( &eventStartsAfter, "event-starts-after", "",