refactor: rename "dev mode" to just sync or "sync mode"

In the spirit of simplifying terminology and preferring transparent over
opaque (or overloaded) phrasing, we've opted to drop the "dev mode" concept in
favor of simply "sync". This more directly describes the functionality and
should be easier to grok.

Specifically, these are the user-facing changes:
1. Users should now use `--sync` instead of `--dev` in the command
line.
2. The `devMode` configuration fields are now called `sync`.
3. The `devMode.sync` and `devMode.syncs` fields are now simply `sync.paths`.

All these changes are backwards compatible.

.gitbook.yaml

@@ -13,6 +13,7 @@ redirects:
   examples/demo-project: ./example-projects/demo-project.md
   examples/tls-project: ./example-projects/tls-project.md
   examples/using-garden-in-ci: ./guides/using-garden-in-ci.md
+  guides/code-synchronization-dev-mode: ./guides/code-synchronization.md
   guides/cert-manager-integration: ./advanced/cert-manager-integration.md
   guides/terraform: ./terraform-plugin/about.md
   providers/conftest-container: ./reference/providers/conftest-container.md

README.md

@@ -84,10 +84,10 @@ Or, say a developer wants to run an end-to-end test from their laptop as they co
 garden test --name <name-of-your-e2e-test-suite>
 ```
 
-Garden also has a special mode called “dev mode” which live reloads changes to your running services—ensuring **blazing fast feedback while developing**. To enable it, simply run:
+Garden also has a special mode called "sync mode" which live reloads changes to your running services—ensuring **blazing fast feedback while developing**. To enable it, simply run:
 
 ```console
-garden dev
+garden deploy --sync
 ```
 
 The Stack Graph is pluggable so how these actions are actually executed depends on the plugins used. Our Kubernetes plugin is currently the most popular, and chances are that’s what you’re here for. To learn more about how Garden works with Kubernetes, check out:

RELEASE_PROCESS.md

@@ -37,7 +37,7 @@ First, you need to prepare the release binaries and run some manual tests:
    - Wait for the CI build job to get the binaries from the [GitHub Releases page](https://github.com/garden-io/garden/releases).
 3. Manual testing (using the pre-release/release binary)
    - On **macOS** or **Linux**, run the `./scripts/test-release.sh <version>` script, where `<version>` should have the format `<major>.<minor>.<patch>-<preReleaseCounter>`, e.g. `0.12.38-0`. The script runs some simple tests to sanity check the release.
-   - On a **Windows** machine, run `garden deploy --dev vote --env remote` in the `vote` example project.
+   - On a **Windows** machine, run `garden deploy --sync vote --env remote` in the `vote` example project.
    - If there are any issues with syncing, consider changing the `services[].devMode.sync[].mode` value(s) to `one-way-replica` and restarting Garden.
    - Change a file in the `vote` service and verify that the code synchronization was successful.
 4. You might need to include some additional commits here. For example, if any other fix(es) should be included from `main`, or if there are any test failures. In that case ypou need a new pre-release:

core/src/cli/helpers.ts

@@ -164,10 +164,10 @@ export function prepareMinimistOpts({
       defaultValues[name] = spec.getDefaultValue(cli)
     }
 
-    if (spec.alias) {
-      aliases[name] = spec.alias
+    for (const alias of spec.aliases || []) {
+      aliases[name] = alias
       if (!_skipDefault) {
-        defaultValues[spec.alias] = defaultValues[name]
+        defaultValues[alias] = defaultValues[name]
       }
     }
   }
@@ -298,8 +298,8 @@ export function processCliArgs<A extends Parameters, O extends Parameters>({
 
   for (const [name, spec] of Object.entries(optSpec)) {
     optsWithAliases[name] = spec
-    if (spec.alias) {
-      optsWithAliases[spec.alias] = spec
+    for (const alias of spec.aliases || []) {
+      optsWithAliases[alias] = spec
     }
   }
 
@@ -352,8 +352,8 @@ export function processCliArgs<A extends Parameters, O extends Parameters>({
   // To ensure that `command.params` behaves intuitively in template strings, we don't want to add option keys with
   // null/undefined values.
   //
-  // For example, we don't want `${command.params contains 'dev-mode'}` to be `true` when running `garden deploy`
-  // unless the `--dev` flag was actually passed (since the user would expect the option value to be an array if
+  // For example, we don't want `${command.params contains 'sync'}` to be `true` when running `garden deploy`
+  // unless the `--sync` flag was actually passed (since the user would expect the option value to be an array if
   // present).
   let opts = <ParameterValues<GlobalOptions> & ParameterValues<O>>(
     pickBy(processedOpts, (value) => !(value === undefined || value === null))
@@ -390,8 +390,10 @@ export function optionsWithAliasValues<A extends Parameters, O extends Parameter
 ): DeepPrimitiveMap {
   const withAliases = { ...parsedOpts } // Create a new object instead of mutating.
   for (const [name, spec] of Object.entries(command.options || {})) {
-    if (spec.alias && parsedOpts[name]) {
-      withAliases[spec.alias] = parsedOpts[name]
+    if (parsedOpts[name]) {
+      for (const alias of spec.aliases || []) {
+        withAliases[alias] = parsedOpts[name]
+      }
     }
   }
   return withAliases
@@ -432,7 +434,9 @@ export function renderOptions(params: Parameters) {
       const prefix = alias.length === 1 ? "-" : "--"
       return `${prefix}${alias}, `
     }
-    const renderedAlias = renderAlias(param.alias)
+    // Note: If there is more than one alias we don't actually want to print them all in help texts,
+    // since generally they're there for backwards compatibility more than normal usage.
+    const renderedAlias = renderAlias(param.aliases?.[0])
     return chalk.green(` ${renderedAlias}--${name} `)
   })
 }

core/src/cli/params.ts

@@ -51,7 +51,7 @@ type GetSuggestionsCallback = (params: GetSuggestionsParams) => string[]
 export interface ParameterConstructor<T> {
   help: string
   required?: boolean
-  alias?: string
+  aliases?: string[]
   defaultValue?: T
   valueName?: string
   hints?: string
@@ -73,7 +73,7 @@ export abstract class Parameter<T> {
   defaultValue: T | undefined
   readonly help: string
   readonly required: boolean
-  readonly alias?: string
+  readonly aliases?: string[]
   readonly hints?: string
   readonly valueName: string
   readonly overrides: string[]
@@ -89,7 +89,7 @@ export abstract class Parameter<T> {
   constructor({
     help,
     required,
-    alias,
+    aliases,
     defaultValue,
     valueName,
     overrides,
@@ -103,7 +103,7 @@ export abstract class Parameter<T> {
   }: ParameterConstructor<T>) {
     this.help = help
     this.required = required || false
-    this.alias = alias
+    this.aliases = aliases
     this.hints = hints
     this.defaultValue = defaultValue
     this.valueName = valueName || "_valueType"
@@ -341,7 +341,7 @@ export class EnvironmentOption extends StringParameter {
     super({
       help,
       required: false,
-      alias: "e",
+      aliases: ["e"],
       getSuggestions: ({ configDump }) => {
         return configDump.allEnvironmentNames
       },
@@ -381,12 +381,14 @@ export function describeParameters(args?: Parameters) {
 
 export const globalOptions = {
   "root": new PathParameter({
-    alias: "r",
+    // TODO: remove this alias in 0.13?
+    aliases: ["r"],
     help:
       "Override project root directory (defaults to working directory). Can be absolute or relative to current directory.",
   }),
   "silent": new BooleanParameter({
-    alias: "s",
+    // TODO: remove this alias in 0.13?
+    aliases: ["s"],
     help: "Suppress log output. Same as setting --logger-type=quiet.",
     defaultValue: false,
     cliOnly: true,
@@ -406,7 +408,7 @@ export const globalOptions = {
     cliOnly: true,
   }),
   "log-level": new ChoicesParameter({
-    alias: "l",
+    aliases: ["l"],
     choices: getLogLevelChoices(),
     help: deline`
       Set logger level. Values can be either string or numeric and are prioritized from 0 to 5
@@ -415,7 +417,7 @@ export const globalOptions = {
     defaultValue: LogLevel[LogLevel.info],
   }),
   "output": new ChoicesParameter({
-    alias: "o",
+    aliases: ["o"],
     choices: Object.keys(OUTPUT_RENDERERS),
     help: "Output command result in specified format (note: disables progress logging and interactive functionality).",
   }),
@@ -431,7 +433,7 @@ export const globalOptions = {
     defaultValue: false,
   }),
   "yes": new BooleanParameter({
-    alias: "y",
+    aliases: ["y"],
     help: "Automatically approve any yes/no prompts during execution.",
     defaultValue: false,
   }),
@@ -444,11 +446,11 @@ export const globalOptions = {
       'Set a specific variable value, using the format <key>=<value>, e.g. `--var some-key=custom-value`. This will override any value set in your project configuration. You can specify multiple variables by separating with a comma, e.g. `--var key-a=foo,key-b="value with quotes"`.',
   }),
   "version": new BooleanParameter({
-    alias: "V",
+    aliases: ["V"],
     help: "Show the current CLI version.",
   }),
   "help": new BooleanParameter({
-    alias: "h",
+    aliases: ["h"],
     help: "Show help",
   }),
   "disable-port-forwards": new BooleanParameter({

core/src/commands/build.ts

@@ -36,7 +36,7 @@ const buildArgs = {
 }
 
 const buildOpts = {
-  "force": new BooleanParameter({ help: "Force re-build.", alias: "f" }),
+  "force": new BooleanParameter({ help: "Force re-build.", aliases: ["f"] }),
   "watch": watchParameter,
   "with-dependants": new BooleanParameter({
     help: deline`
@@ -112,7 +112,7 @@ export class BuildCommand extends Command<Args, Opts> {
             action,
             force: opts.force,
             forceActions: [],
-            devModeDeployNames: [],
+            syncModeDeployNames: [],
             localModeDeployNames: [],
           })
       )

core/src/commands/create/create-module.ts

@@ -43,7 +43,7 @@ const createModuleOpts = {
     defaultValue: defaultConfigFilename,
   }),
   interactive: new BooleanParameter({
-    alias: "i",
+    aliases: ["i"],
     help: "Set to false to disable interactive prompts.",
     defaultValue: true,
   }),

core/src/commands/create/create-project.ts

@@ -41,7 +41,7 @@ const createProjectOpts = {
     defaultValue: defaultProjectConfigFilename,
   }),
   interactive: new BooleanParameter({
-    alias: "i",
+    aliases: ["i"],
     help: "Set to false to disable interactive prompts.",
     defaultValue: true,
   }),

core/src/commands/delete.ts

@@ -196,7 +196,7 @@ export class DeleteDeployCommand extends Command<DeleteDeployArgs, DeleteDeployO
         dependantsFirst,
         force: false,
         forceActions: [],
-        devModeDeployNames: [],
+        syncModeDeployNames: [],
         localModeDeployNames: [],
       })
     })

core/src/commands/deploy.ts

@@ -41,12 +41,12 @@ export const deployOpts = {
   "force": new BooleanParameter({ help: "Force re-deploy." }),
   "force-build": new BooleanParameter({ help: "Force re-build of build dependencies." }),
   "watch": watchParameter,
-  "dev-mode": new StringsParameter({
-    help: deline`The name(s) of the deploys to deploy with dev mode enabled.
+  "sync": new StringsParameter({
+    help: deline`The name(s) of the deploys to deploy with sync enabled.
       Use comma as a separator to specify multiple names. Use * to deploy all
-      with dev mode enabled.
+      supported deployments with sync enabled.
     `,
-    alias: "dev",
+    aliases: ["dev", "dev-mode"],
     getSuggestions: ({ configDump }) => {
       return Object.keys(configDump.actionConfigs.Deploy)
     },
@@ -57,10 +57,10 @@ export const deployOpts = {
     deploys with local mode enabled. When this option is used,
     the command is run in persistent mode.
 
-    This always takes the precedence over dev mode if there are any conflicts,
-    i.e. if the same deploys are passed to both \`--dev\` and \`--local\` options.
+    This always takes the precedence over sync mode if there are any conflicts,
+    i.e. if the same deploys are passed to both \`--sync\` and \`--local\` options.
     `,
-    alias: "local",
+    aliases: ["local"],
     getSuggestions: ({ configDump }) => {
       return Object.keys(configDump.actionConfigs.Deploy)
     },
@@ -74,12 +74,12 @@ export const deployOpts = {
   "skip-dependencies": new BooleanParameter({
     help: deline`
     Deploy the specified actions, but don't build, deploy or run any dependencies. This option can only be used when a list of Deploy names is passed as CLI arguments.
-    This can be useful e.g. when your stack has already been deployed, and you want to run specific deploys in dev mode without building, deploying or running dependencies that may have changed since you last deployed.
+    This can be useful e.g. when your stack has already been deployed, and you want to run specific deploys in sync mode without building, deploying or running dependencies that may have changed since you last deployed.
     `,
-    alias: "nodeps",
+    aliases: ["nodeps"],
   }),
   "forward": new BooleanParameter({
-    help: `Create port forwards and leave process running without watching for changes. This is unnecessary and ignored if any of --dev/--dev-mode or --local/--local-mode are set.`,
+    help: `Create port forwards and leave process running without watching for changes. This is unnecessary and ignored if any of --sync or --local/--local-mode are set.`,
   }),
 }
 
@@ -106,8 +106,8 @@ export class DeployCommand extends Command<Args, Opts> {
         garden deploy my-deploy            # only deploy my-deploy
         garden deploy deploy-a,deploy-b    # only deploy deploy-a and deploy-b
         garden deploy --force              # force re-deploy, even for deploys already deployed and up-to-date
-        garden deploy --dev=my-deploy      # deploys all deploys, with dev mode enabled for my-deploy
-        garden deploy --dev                # deploys all compatible deploys with dev mode enabled
+        garden deploy --sync=my-deploy     # deploys all deploys, with sync enabled for my-deploy
+        garden deploy --sync               # deploys all compatible deploys with sync enabled
         garden deploy --local=my-deploy    # deploys all deploys, with local mode enabled for my-deploy
         garden deploy --local              # deploys all compatible deploys with local mode enabled
         garden deploy --env stage          # deploy your deploys to an environment called stage
@@ -123,7 +123,7 @@ export class DeployCommand extends Command<Args, Opts> {
   outputsSchema = () => processCommandResultSchema()
 
   isPersistent({ opts }: PrepareParams<Args, Opts>) {
-    return !!opts["dev-mode"] || !!opts["local-mode"] || !!opts.forward
+    return !!opts["sync"] || !!opts["local-mode"] || !!opts.forward
   }
 
   printHeader({ headerLog }) {
@@ -175,7 +175,7 @@ export class DeployCommand extends Command<Args, Opts> {
     }
 
     const localModeDeployNames = getMatchingDeployNames(opts["local-mode"], initGraph)
-    const devModeDeployNames = getMatchingDeployNames(opts["dev-mode"], initGraph).filter(
+    const syncModeDeployNames = getMatchingDeployNames(opts.sync, initGraph).filter(
       (name) => !localModeDeployNames.includes(name)
     )
 
@@ -192,7 +192,7 @@ export class DeployCommand extends Command<Args, Opts> {
           forceBuild: opts["force-build"],
           skipRuntimeDependencies,
           localModeDeployNames,
-          devModeDeployNames,
+          syncModeDeployNames,
         })
     )
 

core/src/commands/helpers.ts

@@ -69,7 +69,7 @@ function printField(name: string, value: string | null) {
 
 export const watchParameter = new BooleanParameter({
   help: "[REMOVED] Watch for changes and update actions automatically.",
-  alias: "w",
+  aliases: ["w"],
   cliOnly: true,
   hidden: true,
 })
@@ -79,6 +79,6 @@ export async function watchRemovedWarning(garden: Garden, log: Log) {
     log,
     key: "watch-flag-removed",
     message:
-      "The -w/--watch flag has been removed. Please use other options instead, such as the --dev/--dev-mode option for Deploy actions. If you need this feature and would like it re-introduced, please don't hesitate to reach out: https://garden.io/community",
+      "The -w/--watch flag has been removed. Please use other options instead, such as the --sync option for Deploy actions. If you need this feature and would like it re-introduced, please don't hesitate to reach out: https://garden.io/community",
   })
 }

core/src/commands/logs.ts

@@ -45,14 +45,14 @@ const logsOpts = {
   }),
   "follow": new BooleanParameter({
     help: "Continuously stream new logs.",
-    alias: "f",
+    aliases: ["f"],
   }),
   "tail": new IntegerParameter({
     help: deline`
       Number of lines to show for each deployment. Defaults to showing all log lines (up to a certain limit). Takes precedence over
       the \`--since\` flag if both are set. Note that we don't recommend using a large value here when in follow mode.
     `,
-    alias: "t",
+    aliases: ["t"],
   }),
   "show-tags": new BooleanParameter({
     help: "Show any tags attached to each log line. May not apply to all providers",
@@ -69,7 +69,7 @@ const logsOpts = {
   }),
   "hide-name": new BooleanParameter({
     help: "Hide the action name and render the logs directly.",
-    alias: "hide-service",
+    aliases: ["hide-service"],
     defaultValue: false,
   }),
 }

core/src/commands/publish.ts

@@ -112,7 +112,7 @@ export class PublishCommand extends Command<Args, Opts, ProcessCommandResult> {
         action,
         forceBuild: opts["force-build"],
         tagTemplate: opts.tag,
-        devModeDeployNames: [],
+        syncModeDeployNames: [],
         localModeDeployNames: [],
 
         force: false,

core/src/commands/run.ts

@@ -71,7 +71,7 @@ const runOpts = {
       Warning: Take great care when using this option in CI, since Garden won't ensure that the runtime dependencies of
       your test suites are up to date when this option is used.
     `,
-    alias: "nodeps",
+    aliases: ["nodeps"],
   }),
 }
 
@@ -221,7 +221,7 @@ export class RunCommand extends Command<Args, Opts> {
           force,
           forceBuild: opts["force-build"],
           action,
-          devModeDeployNames: [],
+          syncModeDeployNames: [],
           localModeDeployNames: [],
           skipRuntimeDependencies,
           // interactive: opts.interactive,