Document addon release process

[MichalBryxi]

Releasing v2 addon is not entirely trivial, so would be good to have a way to tell folks how to do this.

cd my-addon-git-repo
cd my-addon # because v2 folder nesting
yarn version && yarn publish

Given that people might prefer variety of tools (yarn / npm / ...) it might be a good idea to document this in *.md file, so that people can follow & adapt.

Proposal:

• Add RELEASE.md file
• This file will have a way to release npm package

[simonihmig]

Note that we support a --release-it opt-in flag, that automates the release process (basically runs https://github.com/rwjblue/create-rwjblue-release-it-setup), and creates a RELEASE.md file.

That doesn't mean we cannot or should not provide instructions for the manual case. But unless there are good reasons to not use this setup, I would recommend that one over any manual steps!

[MichalBryxi]

Aha TIL about --release-it. Automated > Manual, for sure.

If I want to generate new addon (and I don't know the steps from the top of my head), I'd go:

• https://cli.emberjs.com/release/writing-addons/
• I might take a look at the CLI commands reference to guess if there is anything useful
• From there I can see that I want to peek at ember addon reference
• And now I think this page is missing respective (--release-it) option, because now it only says:

ember addon <addon-name> <options...>
  Generates a new folder structure for building
   an addon, complete with test harness.
  --dry-run (Boolean) (Default: false)
    aliases: -d
  --verbose (Boolean) (Default: false)
    aliases: -v
  --blueprint (String) (Default: addon)
    aliases: -b <value>
  --skip-npm (Boolean) (Default: false)
    aliases: -sn
  --skip-bower (Boolean) (Default: false)
    aliases: -sb
  --skip-git (Boolean) (Default: false)
    aliases: -sg
  --yarn (Boolean)
  --directory (String)
    aliases: -dir <value>
  --lang (String) Sets the base human language of the addon's own test application via index.html

So maybe first step would be to improve the documentation at cli.emberjs.com? Trying to confirm & that I'm not doing something silly here.

Second thing, and I know that's heavily subjective so putting it more as a question, would be that I would recommend having a system to help with releasing v2 addon by default? I don't really care if it's npm script or create-rwjblue-release-it-setup or something completely different. But I do believe that ember addon <addon-name> without any options should provide the best DX for most users? And not having to hunt for information how to publish v2 addon to npm registry seems like better DX for most users in my mind?

[simonihmig]

So, all the documentation links and ember help addon refer to the official addon blueprint, which is the v1 one. This one is still more experimental, or at least unofficial. Eventually it is expected to become the default one hopefully, but that needs more work here and an RFC.

So maybe first step would be to improve the documentation at cli.emberjs.com? Trying to confirm & that I'm not doing something silly here.

Yeah, but that will be basically be one thing the RFC will need to suggest. So that's not going to happen that soon...

And yes, this blueprint adds a few non-standard CLI options like --release-it that the default ember addon command does not support. So that's why they are not listed unfortunately. They will once the RFC has been accepted and the work to backport this blueprint as the default one is done.

Second thing, and I know that's heavily subjective so putting it more as a question, would be that I would recommend having a system to help with releasing v2 addon by default?

I am open for discussing that. As a matter of fact, the release setup was once added by default, when there was no way to opt-in or -out of it. After the --release-it flag was added by #22, it became optional and off by default. So again, we could make it opt-out instead of opt-in if folks prefer that. Related: #9

[NullVoxPopuli]

I think there are two more release strategies we should add as options -- which I think strengthens the argument to have none enabled by default?

The two I'd like to add are:

• the automated (entirely C.I. handled, whereas release-it is still human~ish) strategy used by an increasing number of ecosystem addons (I think the adopted by the adopted addon program?) idk why but I feel like @chancancode might know what this is -- I don't know if that's true.. but for some reason my brain thinks there is a relation there?
• the semantic setup, which is semantic-commit + semantic-release -- there are tradeoffs to semantic commits, but other than having a commit prefix (in at least one commit per PR (merge commit counts (and is where I add the prefix from community member submissions)), it's totally hands off. used by many of my addons, such as ember-resources -- this is on the extreme end of the automation spectrum where main is always releasable -- this would make it hard for folks who like to do lots of breaking change commits in prep for a major over a long period of time, but could be managed with a vNext branch that is then merged into main
• changeset -- which is in use by XState, and Starbeam -- I personally need to look in to how this works, but it looks legit, gives you the best changelog generation, imo

---

Update, I've been moving all my stuff (including ember-resources) over to Changesets, because semantic-release has too many caveats and rough edges around monorepos, and I wanted something that "just worked"

[NullVoxPopuli]

I've completely 180'd on this, as I consider release strategy separate from project blueprints.

While having a release strategy is important, and folks should know how to do it -- it's not a concern of ember (these tools work everywhere, basically).

We absolutely should still document some stuff on the guides -- and we need a lot more addon docs on the guides anyway ... as there are basically none.

I removed release-it from this blueprint here: #323

For automated releases, the embroider/tooling team now has a "release from anywhere" tool, which can be setup in one command: npx create-release-plan-setup@latest --update -- and then is entirely hands off from there -- this is a layering technique because release automation is a thing that can be done to any repo, so it makes sense to have the setup outside.

We also don't need to maintain any code here 🎉