search

CircleCI-Public / orb-tools-orb

Various tools for authoring and publishing CircleCI orbs
https://circleci.com/orbs/registry/orb/circleci/orb-tools
MIT License
51 stars 74 forks source link

"No description" error is slightly confusing to read #187

Closed FelicianoTech closed 1 year ago

FelicianoTech commented 1 year ago

This applies to the current release of the orb-tools orb, which I think it 11.6 but also some older versions.

If you have something without a description, this is the error provided by the review job:

Orb components are not invalid without descriptions, but these descriptions appear on the Orb Registry for documentation and provide a better experience.

While the first half of that sentence is technically correct, it feels oddly worded to me.

I'm not great with writing but maybe something like this?

"Orb components are not invalid without descriptions, but these descriptions appear on the Orb Registry for documentation and provide a better experience."

"While descriptions are optional in orb schema, they are strongly recommended when publishing to the Developer Hub. Orb components descriptions become documentation which provides a better experience for everyone.

adamdmharvey commented 1 year ago

Just to ref to the direct code in case someone wants to take a stab:

https://github.com/CircleCI-Public/orb-tools-orb/blob/02a882d119446dc7c5e9861e3201b621238e7ad3/src/scripts/review.bats#L17-L31

I like your suggestion (the last sentence) @felicianotech !

adamdmharvey commented 1 year ago

I'll also note, this sort of double negative pattern is also used here and both could be refactored in a single PR maybe?

https://github.com/CircleCI-Public/orb-tools-orb/blob/02a882d119446dc7c5e9861e3201b621238e7ad3/src/scripts/review.bats#L138

KyleTryon commented 1 year ago

On it, thanks folks! Slapping it on to #181