Orb usage examples are wrong - recommend adding a job to the orb to make them right

[gavinclarkeuk]

Version:

0.4.2

What happened:

The usage examples for the Circle Orb suggest a job is provided by the orb, when it is in fact a command. This means the examples don't actually work.

Instead of doing this:

description: >
  Sample catalog-info.yaml validation
usage:
  version: 2.1
  orbs:
    entity-validator: "roadiehq/backstage-entity-validator@0.3.0"
  workflows:
    use-entity-validator:
      jobs:
        - entity-validator/validate:
            path: catalog-info.yaml

You actually need something like this:

description: >
  Sample catalog-info.yaml validation
usage:
  version: 2.1
  orbs:
    entity-validator: "roadiehq/backstage-entity-validator@0.4.2"

jobs:
  validate:
    docker:
      - image: cimg/node:lts
    steps:
      - checkout
      - entity-validator/validate:
          path: catalog-info.yaml

workflows:
  use-entity-validator:
    jobs:
      - validate

Expected behavior:

Whilst this could just be a documentation update, ideally the orb would provide both a job and command. The job would minimise the amount of config required to get something up and running quickly, and also mean the examples would work

Additional Information:

I'm happy to make a PR with the changes to add a job, but I'm a bit nervous because the build doesn't actually test the orb is working (https://github.com/RoadieHQ/backstage-entity-validator/issues/46)

[roadie-bot]

https://app.shortcut.com/larder/story/9600

[dtuite]

Thanks for reporting this @gavinclarkeuk. We, unfortunately, do not have the bandwidth to tackle this right now. We would love a PR though if you can get the test going.