Additional docs for JobArgs.Kind

job.go

@@ -20,7 +20,19 @@ type Job[T JobArgs] struct {
 // serialized, unless skipped with a struct field tag.
 type JobArgs interface {
 	// Kind is a string that uniquely identifies the type of job. This must be
-	// provided on your job arguments struct.
+	// provided on your job arguments struct. Jobs are identified by a string
+	// instead of being based on type names so that previously inserted jobs
+	// can be worked across deploys even if job/worker types are renamed.
+	//
+	// Kinds should be formatted without spaces like `my_custom_job`,
+	// `mycustomjob`, or `my-custom-job`. Many special characters like colons,
+	// dots, hyphens, and underscores are allowed, but those like spaces and
+	// commas, which would interfere with UI functionality, are invalid.
+	//
+	// After initially deploying a job, it's generally not safe to rename its
+	// kind (unless the database is completely empty) because River won't know
+	// which worker should work the old kind. Job kinds can be renamed safely
+	// over multiple deploys using the JobArgsWithKindAliases interface.
 	Kind() string
 }