I’ve recently started working on my first orb (zzamboni/leanpub, feedback welcome). I have several jobs and commands which share the same base set of parameters, so I have declared them as a YAML anchor near the top of my single-file orb.
I was thinking of destructuring the orb, but it seems that in YAML references cannot be used across multiple files (I guess each .yml file in the tree gets validated separately?). This is what I get:
> circleci config pack src
Error: Failed trying to marshal the tree to YAML : yaml: unknown anchor 'base-leanpub-params' referenced
Is this possible, or should I just stay with a single-file orb due to this?
In the orb I’m writing most commands and jobs take the same two parameters (book-slug and api-key) with the same default values. To avoid repeating their declarations in every block, I put them at the top with an anchor, and use it in commands and jobs as needed. You can see this in Github: https://github.com/zzamboni/leanpub-orb/blob/master/src/%40orb.yml#L10-L18.
Since this is my first orb (and I only recently started using CircleCI at all), maybe I’m going about it the wrong way? Maybe there is some other way to pass this information around without using parameters. I’d appreciate any feedback about the structure and code in my orb as well
You’ve definitely got the right idea! Parameters are the best way to pass values around between your jobs and commands, and it’s definitely a best practice to keep those parameter names consistent. What you’re exposing here is a feature we should support—and likely will at some point: top-level parameter declarations for an orb. So thank you!
In the interim, you could either:
Keep your orb structured the way it is, and accept that your code will have to be a bit less DRY than ideal
Stop using the destructured format, so your orb is all a single file, and use YAML anchors to DRY up your parameters syntax
I’d recommend the former, personally, as I think the destructured syntax is useful enough to make lack of YAML anchor support an acceptable cost.
But we should provide the support to make this kind of thing unnecessary! I think users have filed requests for this feature already at ideas.circleci.com—please vote for it so we can prioritize the development work accordingly
I couldn’t find a relevant entry for this at ideas.circleci.com - I may file a new one.
I would like to semi-hijack the thread to ask about your sentence:
I think the destructured syntax is useful enough to make lack of YAML anchor support an acceptable cost.
Could you help me understand what is so useful about destructured syntax? I understand that you get smaller, hopefully easier-to-understand files, but on the other hand, if you want to make a global change (e.g. rename a parameter all over the place) you have to edit many files, whereas in a single file you can do this very easily. Plus, you lose the ability to use features such as YAML anchors and references. Furthermore, trying to read a destructured orb becomes harder by having to traverse multiple files.
Maybe I’m missing something because the orb I’ve worked with so far is relatively small - maybe destructuring becomes more useful for larger, more complex orbs.
I’m coming at this as a maintainer of many circleci orbs, many of which are large/complex. In our case, what the destructured syntax does is make the entire development process more modular. Say you create a command in one orb, but decide it’s a better fit for another orb. You can just drop the command’s YAML file into the other orb.
But for developers working on a smaller, singular orb, the single-file structure may certainly win out, for reasons that also make sense. Personally, even for a small orb, I find the destructured directory/file tree structure easier to parse as a developer. But others may feel otherwise.
