Requests to improve documentation for plugin developers

[drewmullen]

Description

I am writing a Plugin for the first time and I have several questions that I have not found answers for in the developer docs. I'm hoping to list out my questions in a plain way to give yall ideas on to potentially improve the docs. Any short form answers you have would also be welcome in this issue 🙏

• Should I pass values using state or as parameters to individual builder Step?
• Examples of annotations available for Config parameters (required... default )?
• Should saving an artifact be baked into the build (like AWS AMIs) or as a postprocessor (docker uses a post processor)? What are the +/- of these approaches? I kind of prefer the docker implementation but I haven't seen that anywhere else
• When does a cleanup step run? during step? What if multistep.ActionHalt is returned? Is there a global cleanup function for after all steps are completed?
• Advice on error handling regarding ui
• Docs on writing acceptance tests

[lbajolet-hashicorp]

Hey @drewmullen,

That's quite the panel of questions 😅, I'll try to address those as best I can, feel free to follow-up as needed:

Should I pass values using state or as parameters to individual builder Step?

That's up to personal preference I'd say, I've seen plugins embed their configs in state, some have parameters that are cherry-picked from the builder's config and into the step(s) that need those values.
I tend to think state is meant to forward runtime information, data that is only available during the process and that can be useful to forward to follow-up steps, but really it's just a global state bag for the process, so feel free to store anything you'd need in there if it's relevant for you.

Examples of annotations available for Config parameters (required... default )?

I presume you're talking about the tags for the parameters? This may be a good idea to add in the docs, but I would suggest taking a look at the scaffolding project (assuming you've started developing your plugin with that), there's some examples of tags that are defined. Mostly what we're interested in are the mapstructure (name of the field in configuration), which can accept ,squash as a special value to allow for the attributes of the squashed configuration to be used without nesting them, and the required tags. Defaults are essentially go's, so I'd redirect you to the default values for primitive types in go.
There's also a few types you can use that we define in the plugin SDK, like Trilean (nilable boolean, defaults to nil).
Right now until we write more documentation on this, I suggest looking at existing plugins for inspiration.

Should saving an artifact be baked into the build or as a postprocessor (docker uses a post processor)? What are the +/- of these approaches? I kind of prefer the docker implementation but I haven't seen that anywhere else

I'm not certain what you mean by "saving an artifact", generally speaking builders and post-processors are able to create artifacts which are propagated to the next consumer (post-processor only since you cannot chain builds). The only difference between post-processors and builders are that post-processors are supposed to consume an artifact, and create a new one from that input.

When does a cleanup step run? during step? What if multistep.ActionHalt is returned? Is there a global cleanup function for after all steps are completed?

I believe you are talking about the Cleanup function of a step here? If so, they're run everytime a build completes, successfully or not. The goal of those is that they remove whatever resource they may have created which is not necessary for the final artifact.
If your step doesn't have anything to clean, you can leave it empty (I believe it must be defined on your step however, even if it does nothing, so the step conforms to the interface).

Advice on error handling regarding ui

May I ask you to elaborate on that? Ui in general are for printing messages directly to the user, while log is used for debug logging (available through the PACKER_LOG=1 envvar).

Docs on writing acceptance tests

AFAIK they do not exist yet, the best advice I can give you here is to use existing plugins for inspiration. We do have a runner for acceptance tests exported by the SDK. I believe since this is a public project, you can access the SDK docs through pkg.go.dev (formatting can definitely be improved).