search

mozilla-services / obs-common

code shared between obs-team repositories
Mozilla Public License 2.0
0 stars 0 forks source link

create a listcommands command #41

Open willkg opened 2 weeks ago

willkg commented 2 weeks ago

I was thinking out loud in https://github.com/mozilla-services/antenna/pull/1100#issuecomment-2457261580 about why I wrote socorro-cmd, but don't generally like it and don't really want to carry it across to all the services we maintain.

That got me thinking that maybe instead of having a script runner we have a command that lists the available commands.

All of our commands are of one of two groups:

  1. installed with a Python package -- we can list these automatically because they're listed in the console_scripts entrypoint package metadata

    https://docs.python.org/3/library/importlib.metadata.html#importlib.metadata.entry_points

    >>> import importlib.metadata
>>> [ep.name for ep in importlib.metadata.entry_points()["console_scripts"] if ep.value.startswith(("obs_common", "crashstats_tools", "honcho"))]
["honcho", "gcs_cli", "pubsub_cli", ...]

  2. located in the /app/bin directory

Given that, we can write a command that lists existing commands without having to manually maintain the list of commands.

Example usage:

> make shell
app> listcommands
Available commands:

honcho   gcs_cli   pubsub_cli  ...

See service developer documentation for more details.

Maybe it lists it by source?:

Example usage:

> make shell
app> listcommands
obs-common commands:

gcs_cli   pubsub_cli   waitfor   ...

crashstats-tools commands:

fetch_data   supersearch   reprocess   ...

/app/bin commands:

db   es   ...

See developer documentation for more details.

It could even be something we add to obs-common and note in our docs.

If we built this script in obs-common, then we maintain it in one place, it gets installed everywhere, and wouldn't have to do much to maintain it.

Shylejasatheesan commented 2 weeks ago

I like the idea of a listcommands command! It would definitely improve developer experience by providing an easy way to discover available commands.

The approach of grouping commands by source (package and /app/bin) and including references to developer documentation seems clear and helpful. Building this script in obs-common ensures centralized maintenance and automatic installation.

Possible Enhancements:

Optional Command Descriptions: Adding brief descriptions for each command could provide further context. Filtering by Package/Directory: Allowing users to filter by package or directory (e.g., listcommands obs-common) could improve discoverability for specific services.