Version 0.22 Tracking

[Gerrit0]

The tracking thread for 0.20 (#1364) worked well to keep me working on it with a specific end goal, rather than just experimenting with different ideas and never actually finishing anything... so here's a thread for 0.22.

I'll be posting an update here every week or two with what I've done. The Version 0.22 project is a good place to look for what remains to be done.

Version 0.22 will be released no later than July 30, 2021.

Note: This was originally slated for version 0.21, but #1567 deserves a minor release, so will be releasing as 0.22 with the same timeline.

---

With version 0.22, I've decided it's finally time to give the default theme some work. The existing one works reasonably well, but has some issues.

1. Maintenance and upgrades are painful. Themes in 0.20 are written in Handlebars, which has worked for 6 years, but is showing it's age.

   • Even though the rendered models are fully typed, we can't take advantage of this for error checking
   • Doing anything more complicated than swapping a bit of markup requires learning how to use handlebars

   Better solutions exist. The plan for 0.22 is to use JSX for templating, which means that themes can be written with TypeScript, just like the rest of your code.

2. There is no good way for plugins to add additional information to a page. Right now, plugins have to either ship a custom theme, or do string find/replaces in order to inject content into the page.
   The plan to fix this is to add hooks into the page which allow plugins to inject content. Further, since the JSX templates are initially serialized to plain objects, event listeners may be used to selectively remove or replace parts of the page.

3. It's 2021. Sites should respect your light/dark theme preferences.

Just doing these three would be fairly simple, but there are a few secondary goals that I'm also trying to meet.

1. Allow better configuration of how TypeDoc renders documentation without requiring creating a whole custom theme. (Default the selected menu options on a generated doc site #307, Ability to customize styles without creating a new theme #1060, Option to hide the legend? #1108)
2. Fix invalid HTML generation (header id conflicts #1135)
3. Fix issues with the themes when the user doesn't have JS turned on. (Expression of the method overloading is broken. #453)

... and because I didn't learn my lesson last time, I'm experimenting with building the new default theme from scratch rather than just copying over the handlebars theme, despite not really enjoying frontend work. If you are interested in helping/leading this effort, please reach out!

[Gerrit0]

This week was mostly focused on maintenance. I fixed 3 bugs and released v0.20.34.

I spent a bit of time experimenting with a design for the default theme (will probably share next week), but most of the time for 0.21 was spent on a11a929, which makes it really easy to add tests that focus on recording what changed for specific issues. This should be a huge benefit to productivity when fixing bugs since it means that the snapshot based testing won't necessarily pick up a ton of changes which aren't relevant to what was actually changed.

[Gerrit0]

It's been a really busy month for me... and will likely be busy next few weeks too, but I am still slowly making progress on this. I've modified the planned release version to 0.22 since there's a PR (#1567) which is going to be done before this, and I don't want to hold up releasing it to wait for this. A couple of the things I had slated for the theme rework will be releasing early, but it's primarily dependency cleanup (fs-extra and ShellJS)

I ran into issues releasing the default theme rework since I realized that the design I'd used to try to clean up the routing logic wasn't flexible enough since it blocked any additional page types being added. I suspect that there's still a good way to do this that I haven't figured out yet.

[Gerrit0]

Okay.... well... it's been a while. 0.21 just released today, so I'm finally getting back to working on this. The "break" was just long enough that I've forgotten almost everything I've done. If I'm going to release 0.22 on the stated date, I need to average roughly 75% of an issue per day, which doesn't look too likely right now. We'll have to see what the weekend brings... I think I'm going to completely drop reworking how the themes are structured... I'll update them to get rid of handlebars, but not do a full redesign here. Once this work is done, doing that redesign will be much easier.

[Gerrit0]

Well, I've learned my lesson here I think. If injecting a release, drop the other release and re-plan it after the injected one is done and has been out for a couple weeks. With the --packages work complete, I think it is more important to work on refactoring to better support larger projects than it is to tackle this. I still want to do it, but given the several OOM bugs that have popped up, it seems far more important to do that first... so this is going back to the "good idea, someday" list, sadly.