search

citkane / typedoc-plugin-versions

Semantic versioning with select dropdown for Typedoc documentation sets
https://citkane.github.io/typedoc-plugin-versions/
MIT License
4 stars 7 forks source link

Automatically infer `stable` and `dev` versions based on semver spec #10

Closed toebeann closed 2 years ago

toebeann commented 2 years ago

Changes in this pull request

Reasoning

Building on the work of #9, it should be relatively simple to automatically and reliably infer whether a given version number is stable or dev based on the semver spec, without a user needing to update their typedoc config.

We can also use the previous stable or dev symlinks to infer which is the latest stable version when we are building docs for a dev version, and vice versa.

Also, when a stable version is released with a version number higher than the latest dev version, the dev version can be considerd 'stale' and ignored. The docs for the old dev version will remain available, but the dev symlink should no longer point to them.

This makes for a much simpler experience for the developer building the docs, and a more intuitive version selector for doc readers.

Examples

Note that for all the below examples, all typedoc-plugin-versions options were left at their defaults, i.e. fully automatic.

Implementation details

Please note that as this package's version is less than 1.0.0, it will be considered dev only when building docs for it. This also means that the stub for makeJsKeys output will need updating when this package releases an automatically inferred stable version (i.e. >=1.0.0 without a prerelease label), or the tests will fail.

toebeann commented 2 years ago

Addendum to my note:

Please note that as this package's version is less than 1.0.0, it will be considered dev only when building docs for it.

However, if you manually mark a version as stable as you presently do, then it will be considered stable :)

toebeann commented 2 years ago

It is worth noting that as of the current state of my modifications, if you build a doc for version e.g. 2.0.0, then later decide to rebuild docs for an earlier version e.g. 1.2.0, that earlier version will be marked as stable if you leave everything on auto. This is then fixed by rebuilding the docs for the latest version. I believe this is how it behaves without my modifications, also - I just haven't gotten around to addressing that in this PR as it's only a minor inconvenience, and not the intended use case (where we only ever build versions with higher numbers - except perhaps dev builds vs. stable builds, which behave appropriately in auto mode with this PR).

In a later PR, it should be possible to eliminate the need to rebuild the latest docs in auto mode with some simple additional logic. However, if you like, I could add it as a change in this PR as well - I just tend to prefer to keep my PRs as tightly focused in scope as possible, though I will admit, this PR is quite tightly coupled with #9 😅

toebeann commented 2 years ago

I have made a PR between the two branches I used for development on my fork to make it easier for you to compare the changes between them: https://github.com/toebeann/typedoc-plugin-versions/pull/1

citkane commented 2 years ago

In a later PR, it should be possible to eliminate the need to rebuild the latest docs in auto mode with some simple additional logic.

Yes, I think this quirk will be OK for now and just added somewhere as a @todo, lest we forget... This PR will move the whole thing into a new level of sophistication, whereas before it was a rather blunt, explicit thing. I am glad that you have stated, and I agree, that the behavior remains explicit when the user sets the 'dev' and 'stable' options.

I can have a better read and understanding of your new code once #9 is merged, and will wait till then. (give me a ping when you are done with the comments) A few things in mind for this with corresponding tests:

toebeann commented 2 years ago

A few things in mind for this with corresponding tests:

  • could there be unforeseen behavior if only 'dev' or 'stable' options are set?

Hmm, I don't believe so, but you're right it would be a nice idea to write tests for this, or at the very least do some testing by hand. I'm not the best when it comes to writing tests for this kind of thing, but I will give it a try. (I confess, as a dev I have had very bad habits when it comes to writing tests in the past i.e. generally avoiding them - finally starting to make a good habit of it now but I'm still more inline with "Test Later Development" than "Test Driven Development" 😅)

  • will the default behavior behave as expected if a previous document build folder is deleted? (probably yes unless you have introduced some kind of memory)

I haven't tested this but I would also expect that probably yes it should behave the same as it currently does.

I had previously considered the idea of introducing a JSON metadata file (i.e. "some kind of memory") that the plugin would produce on each docs build, and store it inside the doc folder for each build, which would mean it would get deleted (and therefore ignored) when deleting that build's folder.

I realised however while developing the branch that it would be much smarter (at least, more efficient) to simply rely on the pre-existing symlinks as the only history we need, since most of the time we only need to know what was considered dev and stable on the previous run, and reading where the corresponding symlinks currently point to will give us that info. It's an upgrade over how it currently behaves, but it isn't perfect. It's "good enough" for most use cases, however.

However, while writing this, I have now also realised that I didn't test whether the path the symlink is pointing to still exists, so that is an edge case not yet addressed in this PR, i.e.:

I'll need to test whether this actually happens, but it is a consideration I hadn't thought of so potentially something I let slip through.

I feel like potentially the best way to effectively address this edge case would be to actually introduce the JSON metadata files as I had originally intended, and to make the logic even more "sophisticated" (read: complex and annoying to maintain 😅) than at present.

I'll mark this PR as draft while I address these concerns.

citkane commented 2 years ago

No panic on this. I invited you as a collaborator, so feel free to release 0.2.0 with the sorting fixed (and hold this PR) if that helps you with your other projects. I am thinking of implementing a changelog, but not sure sure yet of the best way. Your thoughts are welcome.

My "other job" is as architect (the building kind), so a broad analogy for test driven design is like trying to create a beautiful space by getting the waterproofing details right first... Not happening. But yet - get the waterproofing details wrong and very soon the beautiful space is meaningless. Oh what philosophy this could spawn :smile:

My head is elsewhere ATM, and I want to give this PR the attention it deserves. I will come back to it, but work away as you see fit.

My gut instinct is, that if you want the behavior to be able to re-build earlier versions which influence the stable symlink, memory will be required. Probably best if this is one metadata structure in a json at the root doc level (next to the doc folders and the index.html redirect). This way, the user can see and understand what is going on without having to dig down.

The plugin run could kick off by auditing this file to determine how the folder landscape has changed, which would determine further paths of action, and then updating it to the new state.

toebeann commented 2 years ago

Just wanting to update as timing has been a bit unfortunate; I'm a bit under the weather at the moment so unfortunately put this on hold for now, will hopefully be back at it in a matter of days if not sooner.

toebeann commented 2 years ago

I am thinking of implementing a changelog, but not sure sure yet of the best way. Your thoughts are welcome.

I'm unsure on this - I've not really looked into implementing changelogs before myself, I usually just rely on people to know to look at the releases page if they're on GitHub. I've released a bunch of things on nexus mods, and there they have their own built in changelog feature and I pretty much just copy PR titles over from my GitHub repos.

I wouldn't be surprised to find out that a GitHub action exists to automatically generate a CHANGELOG.md file, but I've not looked into it. Then you could just link to it at the end of the README. In which case, you would want to make sure any important change/bugfix is handled only via PRs and never via direct commits on dev/main.

My gut instinct is, that if you want the behavior to be able to re-build earlier versions which influence the stable symlink, memory will be required. Probably best if this is one metadata structure in a json at the root doc level (next to the doc folders and the index.html redirect). This way, the user can see and understand what is going on without having to dig down.

The plugin run could kick off by auditing this file to determine how the folder landscape has changed, which would determine further paths of action, and then updating it to the new state.

Yeah, I agree with you on this. I'll go ahead and implement as part of this PR.

I have some other ideas for features to implement where it might be an idea to discuss them with you before I start working on them in case you have thoughts. I'll open issues for them so we can discuss them while keeping this PR on-topic.

On a related note, if you have your own feature ideas or a list of things that need to be done before this plugin can reach v1.0, it might be an idea to open issues for them - then when someone has free time, we can work towards v1.0!

toebeann commented 2 years ago

@citkane, I have updated this PR to take care of the issues that were brought up: