Publishing docs / examples

Ecosystem Orbs
1

Can someone clarify the publishing process?

The docs in https://circleci.com/docs/2.0/creating-orbs/ explain how publishing a dev version works
In: sandbox/hello-world@dev:first, what do dev and first represent? Does dev just create a 0.0.x version, or are dev versions somehow special in other ways?

If I’m releasing a normal version, doing sandbox/hello-world@1.0.2 seems to work fine, but if I want to use the ‘patch’ / ‘minor’ example, do I reference the current version and then “patch” or whatever?

2

Assuming you have already previously published sandbox/hello-world@1.0.2, and you want to:

Publish your myorb.yml Orb file as a new minor: circleci orb publish increment myorb.yml sandbox/hello-world minor

Publish your myorb.yml Orb file as a new major: circleci orb publish increment myorb.yml sandbox/hello-world major

My assumption is that your Orb will be incremented to 1.1.0 and 2.0.0 respectively (based on the segment you pas as the last argument).

3

dev is its own label, just as 1.0.0 is a label.

dev does not correspond to a version number in any way.

dev is used to indicate to you, as a user, that the Orb you are consuming is in development, and may not be stable. Furthermore, a dev label has special properties, such as, it’s mutable. A dev:___ label may have its Orb contents replaced at any time.

That is in stark contrast to a semantic version number, such as 1.0.0, in which the Orb content for 1.0.0 can never be changed, ever.

4

@hutson I guess the part that confused me was that it says that it has you do a patch release directly from sandbox/hello-world@dev:first, and doesn’t really clarify if (or how) you can use the @dev release. The information about it being mutable is helpful. I looked and there are docs about the dev versioning, just below the semver ones.

Does @dev:first correspond to a numeric version at all, and if not, why do the docs say to refer to it via the tag above? Can I continue publishing to @dev once I’ve done an initial release, and if so, again, how do I reference it? Is ‘first’ just an arbitrary identifier, or do I use that too?

[edit] it looks like, from the CLI, that the identifier is an arbitrary text string

lana% circleci orb publish src/node/orb.yml foo/bar@dev            
Error: Invalid version specified for publishing: dev (expected either a semver-style version string in x.y.z format, or a development-style version string in dev:* format.)
lana% circleci orb publish src/node/orb.yml foo/bar@dev:foo
[works]
5

It does not.

The workflow recommended by Circle CI is to publish an Orb to a dev label first.

circleci orb publish src/node/orb.yml foo/bar@dev:foo

^ You’re example is what they expect.

Once the publish completes, you may reference that dev label in your Circle CI configuration:

orbs:
  node: foo/bar@dev:foo

The idea is that you publish your Orb under a dev label, and then you test that Orb.

Once you are confident that your Orb is working correctly, you promote the Orb pointed to by a dev label.

circleci orb publish promote foo/bar@dev:foo patch

The promotion creates a copy of the Orb, and then gives it a semantic version label based on the segment you specified (patch in this case).

It determines the version by looking at the latest semantic version number you published, and increments the PATCH segment.

1 Like
6

Every dev label begins with dev. The part after the colon, :, is up to you.

dev is simply a way to communicate to you that the Orb is in development.

You may publish multiple dev Orbs.

To publish multiple Orbs, you can give each one a unique name after the colon.

So you could publish a dev:simple Orb and a dev:difficult Orb at the same time.

1 Like
7

@wyardley I recommend taking a look at some of the automated publishing processes in our open-source orb repos—we’re still working out a 100% best practice, but there’s a lot of good iterations. For example, from the monorepo:

workflows:
  version: 2
  main:
    jobs:
      - lint
      - build

      - dev-release:
          requires:
            - build
            - lint

      - trigger-downstream:
          requires:
            - dev-release
          filters:
            branches:
              only: master
          context: orb-publishing

      - hold:
          type: approval
          requires:
            - trigger-downstream
          filters:
            branches:
              only: master

      - dev-promote-patch:
          requires:
            - hold
          filters:
            branches:
              only: master
          context: orb-publishing

and, in detail, a dev release command:

circleci orb publish ${ORB}orb.yml circleci/${orbname}@dev:${CIRCLE_BRANCH}-${CIRCLE_SHA1} --token $CIRCLECI_API_TOKEN

and prod release command:

circleci orb publish promote circleci/${orbname}@dev:${CIRCLE_BRANCH}-${CIRCLE_SHA1} patch --token $CIRCLECI_API_TOKEN

(${orbname} because these commands are running in a loop within the monorepo and being applied to multiple orbs.)

Or, a simpler, single-orb example:

The key thing to note is: if you automate your publishing, you can dev-publish with the commit hash appended to the tag, and then use that same commit hash in your later job to promote the orb to prod.

This process will get firmed up in the coming months, I think, and when we have something that feels established enough, we can describe it more officially in our documentation.

We also provide the Orb Tools Orb to help folks with this process:

https://circleci.com/orbs/registry/orb/circleci/orb-tools

What it provides doesn’t quite match the previous examples, but that’s an example of our best practices still being a bit in flux. We’ll continue actively developing the orb tools orb, as well, to make it as easy as possible for end users to automate their own orb building/testing/publishing on CircleCI.

Thanks!