fix: keep known initialisms together in generated command names - #60
Conversation
The camelToKebab conversion used for CLI command/flag names inserted a dash before every uppercase letter, splitting initialisms like BGP, SSH, IP, VLAN, and API into commands such as b-g-p, s-s-h-key, and i-p-address. Add a shared internal/casing package that recognizes a list of known initialisms and keeps them as a single word, fixing commands like bgp, ssh-key, ip-address, and oauth.
Digits like the "2" in OAuth2 or the "4"/"6" in IPv4/IPv6 were treated as a new word boundary, producing oauth-2-token instead of the well-known spec name oauth2-token. Trailing digits now attach to the preceding word like other suffixes.
Run 'make docs' to pick up the renamed commands (e.g. b-g-p -> bgp, create-a-p-i-key -> create-api-key, o-auth2-token -> oauth2-token) from the camelToKebab fix.
|
As a backwards compatibility bridge, we could consider matching action names regardless of hyphens. |
|
I'm tempted to remove "-api" from action and service names as this is another trait of the published API specs whose faithful representeation detracts from CLI UX. I'm also considering adding logical service names that would proxy and aggregate for actions among existing service names. The actual service names could then be aliased, hidden, or dropped. The Docs site does similar:
For the CLI, the wrapper name would not have nested service names. The operations across the various services would be made available under the wrapper service name. Conflicts would need to be flagged on build. |
This is v0, so I think it's reasonable to break the old, poorly-named commands and preferable not to add that complexity (it will never get cleaned up once it's in there).
Reasonable but I'm not clear if this is something we could get by making changes somewhere upstream (catalog, SDK, somewhere else) that would provide broader benefit.
This definitely seems like something we should drive from the catalog rather than here. |
|
This PR is included in version 0.4.1 🎉 |
2 participants
Summary
b-g-p,s-s-h-key,i-p-address,v-l-a-ns,o-auth2-token, etc.internal/casing.CamelToKebab, which recognizes a small list of known initialisms (BGP, SSH, IP, API, VLAN, VRF, CSP, VC, EIA, GET/POST/etc., UUID, ID, ...), normalizes the irregularOAuthcasing, and keeps version-style digit suffixes (OAuth2,IPv4,IPv6) attached to their word instead of splitting them off.camelToKebabimplementations ininternal/register/register.goandinternal/parser/extractor.gowith calls to the shared helper.docs/viamake docsso the generated docs match the renamed commands (CI checks this withmake docs-check).Before → after (discovered via
git grep -E '[a-z]-[a-z]-[a-z]'):b-g-p→bgp,b-g-p-session→bgp-sessions-s-h-key→ssh-key,find-s-s-h-keys→find-ssh-keysi-p-address→ip-address,v-l-a-ns→vlans,v-r-fs→vrfscreate-a-p-i-key→create-api-keyget-o-auth→get-oauth,o-auth2-token→oauth2-tokenvlan-c-s-p-connection→vlan-csp-connectionvrf-b-g-p-neighbors→vrf-bgp-neighborsLegitimate single-letter hyphenated terms like
a-side/z-sideare unaffected.Test plan
go build ./...go vet ./...go test ./...(addedinternal/casing/casing_test.go)make docsand committed the regenerated files somake docs-checkpasses in CImetalv1 bgp,metalv1 ip-addresses,metalv1 ssh-keys,metalv1 vlans,metalv1 vrfs, andaccesstokenv1 oauth2-tokencommands