docs: mention name clashing between custom goals and options when wri…

…ting plugins (pantsbuild#17899)
tylerscheuble · Dec 30, 2022 · 6a19b94 · 6a19b94
1 parent dae18b7
commit 6a19b94
Show file tree

Hide file tree

Showing 2 changed files with 8 additions and 0 deletions.
diff --git a/docs/markdown/Writing Plugins/rules-api/rules-api-goal-rules.md b/docs/markdown/Writing Plugins/rules-api/rules-api-goal-rules.md
@@ -201,3 +201,7 @@ async def hello_world(console: Console, specs_paths: SpecsPaths) -> HelloWorld:
 `SpecsPaths.files` will list all files matched by the specs, e.g. `::` will match every file in the project (regardless of if targets own the files).
 
 To convert `SpecsPaths` into a [`Digest`](doc:rules-api-file-system), use `await Get(Digest, PathGlobs(globs=specs_paths.files))`.
+
+> 📘 Name clashing
+>
+> It is very unlikely, but is still possible that adding a custom goal with an unfortunate name may cause issues when certain existing Pants options are passed in the command line. For instance, executing a goal named `local` with a particular option (in this case, the global `local_cache` option), e.g. `./pants --no-local-cache local ...` would fail since there's no `--no-cache` flag defined for the `local` goal. 
diff --git a/docs/markdown/Writing Plugins/rules-api/rules-api-subsystems.md b/docs/markdown/Writing Plugins/rules-api/rules-api-subsystems.md
@@ -115,3 +115,7 @@ async def demo(shellcheck: Shellcheck) -> LintResults:
     config_discovery = shellcheck.config_discovery
     ...
 ```
+
+> 📘 Name clashing
+>
+> When adding custom options, make sure their name does not start with an existing goal name. For instance, passing a boolean option named `check_foobar` as `--check-foobar` in the command line would fail since Pants would think you are trying to pass the `--foobar` flag in the built-in `check` goal scope.