Typedoc: Consider automatic releases

[tsvetomir]

• [x] I have checked issues with enhancement label and found no duplicates

Problem

Manual releases usually lag behind as they involve humans. That's fine — humans have stuff to do.

Suggested Solution

• Set up Semantic Release and let it do it's thing. No more "New release?" issues, yay!
• Optionally, set up gated releases by adding a develop branch. Trigger releases by fast-forwarding master to it.

[JustinBeckwith]

I have set this up on many of my personal projects, and would be more than happy to help :)

[aciccarello]

I like this idea to help get releases out faster but don't have experience setting this up. I'd be happy to discuss this (either here or on gitter).

For now, I'm working on getting a manual release out.

[JustinBeckwith]

Here's an example of a repository where I have this set up:
https://github.com/JustinBeckwith/linkinator

The workflow kinda goes like this:

• For every commit that hits master, you enforce the conventional commits spec.
• Every time a commit hits master, a changelog is automatically produced via conventional-changelog
• The release goes out automatically, with the generated changelog, and using conventional commits to understand the semverity of the change.

To implement it:

• I like to use the commitlint probot to do status checks for me. Alternative you can set up your own CI using the commitlint npm module
• Install the semantic-release npm module into your dev dependencies
• Set up a CI job that runs only when commits hit master. The official documentation has lots of great docs for this step. Here is what mine looks like.
• To make it work, you have to be ok with using your GitHub token and npm token available in your . CI config

There's a lot here. If you need any help at all, or have any questions - just ping me here! I spend too much time on GitHub.

[Gerrit0]

I'm looking at this again, I've been trying to conform to conventional commits (I misunderstood some of the prefixes, only think I fully grasped them today) for a while here.

Thanks for the example repo @JustinBeckwith!

I have a few unresolved questions that I'm still researching:

1. TypeDoc is still in a 0.x release - so semver doesn't really apply. How does semantic-release handle this? I don't want to change the current release strategy to go past 1.x until I am ready to commit to a fairly stable API (unfortunately pretty far off still). We currently:
   
   
   
   • Release minor changes that are unlikely to break plugins/themes as patch versions
   
   
   • Release larger features + breaking changes every couple of months as a minor version
   
   
2. Does this work correctly with npm's 2fa?

Maybe as a first step I should try moving TypeDoc's automatic unit tests over to GitHub actions from Travis. I haven't used GitHub actions before, and don't really understand how they work yet.

(I really don't want to get this wrong and trigger a ton of releases by accident while trying to fix it - so I guess I should actually do it on a test repo first)

[JustinBeckwith]

👋 hello!

TypeDoc is still in a 0.x release - so semver doesn't really apply.

Semver rules do apply here! Semver specifically has clauses for how you are to treat 0.x releases. Bug fixes can still be released with patches when using the fix:, prefix with conventional commits. It just so happens that any feat: is going to bump the minor, which would result in what's considered a breaking change. I know it sounds like I'm being pedantic, just want to make it clear there are rules :)

Now the fact that TypeDoc is still an 0.x release is a different beast. My 2 cents here - just go 1.0. That doesn't mean you don't get to make breaking changes! In many modules my team owns, we snap to doing semver major releases once a year, centered around Node.js LTS versions going out of support. Version numbers are free :) Going 1.0, and then needing to cut a 2.0 a few months later is no big deal in my book. Staying at 0.x however, makes upgrades painful due to the mixing of new features and actual breaking changes.

Does this work correctly with npm's 2fa?

Sadly, it does not. I am personally ok with that, but understand if others aren't. To get around this problem, and still publish npm modules in a secure way, folks on my team wrote this:
https://github.com/GoogleCloudPlatform/wombat-dressing-room/

It is probably a little overkill for most OSS projects, but if you absolutely need 2FA, and want automated publishing, it can do that for you :)

Hope all of this helps!

[Gerrit0]

Am I missing something? Item 4 seems pretty explicit that major version 0 means breaking changes can happen anywhere... being pedantic is good :) I want to be clear!

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

---

Going 1.0, and then needing to cut a 2.0 a few months later is no big deal in my book.

How about 1 commit later? TypeDoc currently inappropriately has nearly everything marked as public, and all but a couple plugins access modules with internal paths since what is exposed through the index is somewhat random...

I make changes that break the public API almost every time I touch the code. Now, not many people use the public API, and those that do usually don't end up touching the parts I change, but it does change. If adding a new feature, unless it is a simple toggle like --disableSources I am virtually guaranteed to break something.

This should slow down considerably once:

1. The models are refactored to be models, not just object bags that everyone throws stuff onto.
2. The converter is refactored to remove the component decorator and respect model boundaries.

But that isn't nearly ready yet... I've done a lot of thinking and a bit of writing about my plans but haven't touched the code yet.

Sadly, it does not. I am personally ok with that, but understand if others aren't....

Neat! I'm personally ok with dropping 2fa, but it is good to know there is a workaround. 2fa is enabled on the main typedoc package, but not on the default themes package, so it doesn't actually provide any extra security that I can tell. @aciccarello, @blakeembrey, do you have an opinion on this?

Thanks for the help!

[Gerrit0]

So, we kind of do this now. I have a GitHub action set up which will automatically publish a new version on change. I don't think we're ready for fully automatic releases, and due to the nature of this project, I doubt we ever will... however, it is good enough that I'm satisfied with the current setup.