Update "Create a plugin docs" to be a how to create a plugin end to end

[lifeiscontent]

Is your feature request related to a problem? Please describe

https://github.com/asdf-vm/asdf/blob/master/docs/plugins/create.md has decent documentation, but I think it would be superior if it was written from the perspective of taking one of the most popular asdf plugins and creating it from scratch talking about things like:

• adding env specific vars for runtimes such as go's GOPATH
• how to support multiple architectures e.g. linux,windows,arm,etc.
• how to compile from source (if needed) or if that is not a goal of asdf, outline it in the docs.

if the docs were written in this way, I'd be more than happy to contribute, but I'm just not familiar enough with the goals of asdf or bash for that matter.

it would also help people build plugins consistently since there is possibility to have such a wide variety, I think documentation from this perspective would be incredibly useful for the community and the overall growth of asdf.

A good example of documentation written this way is: https://storybook.js.org/docs/react/writing-stories/introduction

they show code, and explain it fairly well, which to me is a much more approachable way to learn.

Describe the proposed solution

outlined above.

Describe similar asdf features and why they are not sufficient

outlined above.

Describe other workarounds you've considered

outlined above.

[Stratus3D]

I'm not opposed to adding more details to that page @lifeiscontent, if you or anyone else would like to take a stab at improving it a PR would be welcome. However that that page is more about documenting the API between asdf and asdf plugins than it is a guide on how to create a plugin. It may be better for us to create a separate plugin guide page that goes from start to finish creating an example plugin, because I think the API documentation we current have is useful for reference.

[lifeiscontent]

@Stratus3D Awesome, I agree, a new page might be better here. Would you have some to chat on discord or something? Again, I don't really understand all the ins and outs of asdf so it'd be nice to have some clarifications on aspects of what should be thought about when developing a plugin and what a good design of a plug-in might look like.

[Stratus3D]

@lifeiscontent I don't normally use discord, but I am on Slack most of the day. I am usually pretty busy so I don't have a lot of time to chat, but I'd be happy to answer any questions you have as I have time.

[lifeiscontent]

@Stratus3D Thanks for the response, I guess as a starting point, are there docs you'd recommend I read up on for things in relation to:

What are the lifecycles of a plug-in? Which commands I can hook into as a plug-in author, what are required and optional?

Is there a particular signature that each hook follows?

Within each hook, how do they interact from the CLI?

I'm just trying to put a visual outline together of how the system as a whole works/should work within the context of a plug-in.

[Stratus3D]

@lifeiscontent so, in order of being most to least accurate and up to date:

• asdf source code itself ultimately the truth
• asdf documentation is accurate, but are sometimes a little behind when it comes new features https://asdf-vm.com/plugins/create.html#what-s-in-a-plugin
• The asdf plugin template repo is a good example of a plugin, but it also is often behind when it comes to new features https://github.com/asdf-vm/asdf-plugin-template

asdf plugins must implement required callbacks, which are simply scripts in the plugin's bin/ directory. Most callbacks are optional.

asdf plugins can also define hooks, but all of them are optional. They are also implemented as callback scripts that only need to exist when needed. They allow plugins to run custom code before or after various asdf events. Most plugins should not need to implement hooks.

All user interaction with plugins should take place through the asdf APIs. Either the CLI (asdf ...), through the .tool-versions file, or asdf environment variables. asdf invokes all plugin callbacks and hooks as necessary.

Hope this helps! Yeah, a visual of this would be good. I don't have the time to create graphviz diagram right now, so feel free to take a stab at it if you want. Thanks!

[lifeiscontent]

@Stratus3D thanks for the write up! Next time I get some down time I'll take a stab at this, and thank you for writing asdf, its a very neat idea! :)

[jthegedus]

The docs have now been updated with more explicit information about each script. The changes were optimized for isolating each script description with the caveat of repetition throughout the page.

Here is a summary of the changes from #1445:

• Overview: describe that each plugin is a git repo
• Quickstart: for getting started with your own plugin via the template or otherwise
• Golden Rules for writing plugins
• table overview of the scripts, single line description, marking if required or optional
• table overview of all environment variables from all scripts
• Required Scripts details section
• Optional Scripts details section
• For the scripts in the details sections:
  • list the env vars available to the script
  • description, including why/how you would use the script (this area can be improved)
  • expected output formats with examples
  • call signature from asdf core
  • CLI commands that may invoke the script

---

While improved, these changes are not a guide to implementing a plugin end to end, so I don't think we can fully close out this issue, but I hope it brings clarity.