sg: Add description field to sg commands (#39240)

dev/sg/internal/run/command.go

@@ -30,6 +30,7 @@ type Command struct {
 	Preamble string `yaml:"preamble"`
 
 	ExternalSecrets map[string]secrets.ExternalSecret `yaml:"external_secrets"`
+	Description     string                            `yaml:"description"`
 
 	// ATTENTION: If you add a new field here, be sure to also handle that
 	// field in `Merge` (below).
@@ -62,6 +63,9 @@ func (c Command) Merge(other Command) Command {
 	if other.Preamble != merged.Preamble && other.Preamble != "" {
 		merged.Preamble = other.Preamble
 	}
+	if other.Description != merged.Description && other.Description != "" {
+		merged.Description = other.Description
+	}
 	merged.ContinueWatchOnExit = other.ContinueWatchOnExit || merged.ContinueWatchOnExit
 
 	for k, v := range other.Env {

dev/sg/sg_run.go

@@ -92,7 +92,10 @@ func constructRunCmdLongHelp() string {
 	fmt.Fprintf(&out, "Available commands in `%s`:\n", configFile)
 
 	var names []string
-	for name := range config.Commands {
+	for name, command := range config.Commands {
+		if command.Description != "" {
+			name = fmt.Sprintf("%s: %s", name, command.Description)
+		}
 		names = append(names, name)
 	}
 	sort.Strings(names)

doc/dev/background-information/sg/reference.md

@@ -87,10 +87,10 @@ Available commands in `sg.config.yaml`:
 * caddy
 * codeintel-executor
 * codeintel-worker
-* debug-env
-* docsite
+* debug-env: Debug env vars
+* docsite: Docsite instance serving the docs
 * executor-template
-* frontend
+* frontend: Enterprise frontend
 * github-proxy
 * gitserver
 * grafana
@@ -101,21 +101,21 @@ Available commands in `sg.config.yaml`:
 * oss-frontend
 * oss-repo-updater
 * oss-symbols
-* oss-web
+* oss-web: Open source version of the web app
 * oss-worker
-* otel-collector
+* otel-collector: OpenTelemetry collector
 * postgres_exporter
 * prometheus
-* redis-postgres
+* redis-postgres: Dockerized version of redis and postgres
 * repo-updater
 * searcher
-* server
+* server: Run an all-in-one sourcegraph/server image
 * storybook
 * symbols
 * syntax-highlighter
-* web
-* web-standalone-http
-* web-standalone-http-prod
+* web-standalone-http-prod: Standalone web frontend (production) with API proxy to a configurable URL
+* web-standalone-http: Standalone web frontend (dev) with API proxy to a configurable URL
+* web: Enterprise version of the web app
 * worker
 * zoekt-index-0
 * zoekt-index-1

sg.config.yaml

@@ -116,6 +116,7 @@ env:
 
 commands:
   server:
+    description: Run an all-in-one sourcegraph/server image
     cmd: ./dev/run-server-image.sh
     env:
       TAG: insiders
@@ -142,6 +143,7 @@ commands:
       - cmd/frontend
 
   frontend:
+    description: Enterprise frontend
     cmd: |
       # TODO: This should be fixed
       export SOURCEGRAPH_LICENSE_GENERATION_KEY=$(cat ../dev-private/enterprise/dev/test-license-generation-key.pem)
@@ -320,16 +322,19 @@ commands:
       CADDY_VERSION: 2.4.5
 
   oss-web:
+    description: Open source version of the web app
     cmd: ./node_modules/.bin/gulp --color dev
     install: yarn --no-progress
 
   web:
+    description: Enterprise version of the web app
     cmd: ./node_modules/.bin/gulp --color dev
     install: yarn --no-progress
     env:
       ENTERPRISE: 1
 
   web-standalone-http:
+    description: Standalone web frontend (dev) with API proxy to a configurable URL
     cmd: yarn workspace @sourcegraph/web serve:dev --color
     install: |
       yarn --no-progress
@@ -339,6 +344,7 @@ commands:
       SOURCEGRAPH_API_URL: https://k8s.sgdev.org
 
   web-standalone-http-prod:
+    description: Standalone web frontend (production) with API proxy to a configurable URL
     cmd: yarn workspace @sourcegraph/web serve:prod
     install: yarn workspace @sourcegraph/web run build
     env:
@@ -347,8 +353,9 @@ commands:
       SOURCEGRAPH_API_URL: https://k8s.sgdev.org
 
   docsite:
+    description: Docsite instance serving the docs
     cmd: .bin/docsite_${DOCSITE_VERSION} -config doc/docsite.json serve -http=localhost:5080
-    install_func: installDocsite
+    install_func: 'installDocsite'
     env:
       DOCSITE_VERSION: v1.8.7 # Update DOCSITE_VERSION in all places (including outside this repo)
 
@@ -515,6 +522,7 @@ commands:
     #       PGUSER: sourcegraph
     #
     # You could also add an overwrite to add `redis-postgres` to the relevant command set(s).
+    description: Dockerized version of redis and postgres
     cmd: docker-compose -f dev/redis-postgres.yml up $COMPOSE_ARGS
     env:
       COMPOSE_ARGS: --force-recreate
@@ -663,6 +671,7 @@ commands:
 
   otel-collector:
     install: docker-images/opentelemetry-collector/build.sh
+    description: OpenTelemetry collector
     cmd: |
       JAEGER_HOST='host.docker.internal'
       if [[ "$OSTYPE" == "linux-gnu" ]]; then
@@ -695,6 +704,7 @@ commands:
   # This will execute `env`, a utility to print the process environment. Can
   # be used to debug which global vars `sg` uses.
   debug-env:
+    description: Debug env vars
     cmd: env
 
   bext:
@@ -933,7 +943,7 @@ commandsets:
       - web-standalone-http-prod
       - caddy
 
-  # For testing out OpenTelemetry stack
+  # For testing our OpenTelemetry stack
   otel:
     checks:
       - docker