Automatic update examples with correct version of the orb

[Gaardsholt]

Describe Request:

It would be great if we could use a template value/variable to always have the examples show the correct version of the orb.

Examples:

Instead of writing the examples like this:

usage:
  version: 2.1
  orbs:
    my-orb: my-namespace/my-orb@dev:1.2.3

We could do something like this:

usage:
  version: 2.1
  orbs:
    my-orb: my-namespace/my-orb@${{ORB_VERSION}}

Supporting Documentation Links:

[KyleTryon]

I am interested. Highly considering this.

A few questions / considerations.

1. What would you expect to happen if you used ${{ORB_VERSION}} (we would like use a syntax similar to << orb.prod.version >>) in an orb that was not your own in the situation where more than one orb is used.
2. In the event a major change is made, the usage examples may incorrectly show out-of-date examples.
   a. If you hard code the version numbers we could at least state that usage example is accurate to the version displayed
   b. Counter-point, if you already use an x.y.z structure as we often do, there is no reason not to.
3. We may need to consider what will be valid when running circleci config validate against the example.
4. Would we want to enforce this as a new "RC" review check?

I think this is feasible. The publish job would use the CircleCI tag when publishing the orb to make an on-the-fly replacement of the template text. I think an expectation would need to be set that this is simply using the tag version in the pipeline and would only be valid on the orb being built, and should not be used on another orb.

Examples

GOOD

usage:
  version: 2.1
  orbs:
    my-orb: my-namespace/my-orb@<< orb.prod.version >>

---

BAD

usage:
  version: 2.1
  orbs:
    my-orb: my-namespace/my-orb@<< orb.prod.version >>
    jq: circleci/jq@<< orb.prod.version >>

It should be possible to warn the user if we know the orb name and namespace, and ensure it is only used on matching lines.

[Gaardsholt]

Sorry for not replying, I totally forgot about this issue !

My comments on your points:

1. I would expect it to be replaced with the published version - I don't care if we use ${{ORB_VERSION}} or @<< orb.prod.version >>.
2. I would say that it is up to the orb author to make sure the examples are updated when doing a major change.

[Gaardsholt]

Is this something that is being worked on?

[david-montano-circleci]

Hello. I think this is worth implementing. But I would try to go a step further and make sure the examples are valid for the specified version.
I will be tackling this in the upcoming weeks.