umbraco/OurUmbraco

Versioned API docs

Closed this issue · 3 comments

abjerner commented

I'm assuming the current API docs are based on the latest stable version of Umbraco, but is doesn't say so specifically.

https://our.umbraco.com/apidocs/ui/#/api
https://our.umbraco.com/apidocs/csharp/

Ideally it should be possible to select a specific version of Umbraco - or at least a specific major version, as Umbraco 8 is going to be released soon. As Umbraco 7 won't be put in the grave when v8 comes out, there will be a need for API docs for both versions.

I had a look at the Our codebase, and found this controller:

https://github.com/umbraco/OurUmbraco/blob/master/OurUmbraco/Documentation/Controllers/DocfxController.cs

It seems to be the one triggering an update of the docs, but this looks to be an integration with AppVeyor. So I'm assuming the controller is called each time a new version of Umbraco is released - so I'm a bit stuck in the code.

What are the HQs thoughts on versioned API docs?

nul800sebastiaan commented

I actually can't remember how we update the API docs at the moment, I think AppVeyor is no longer used.

But yes, it's a good idea to make a versioned version.. which also leads to the question: how? There's 2 docs builds:

  1. Gulp build for the Angular docs
  2. DocFx build available from build.ps1 (can't remember exactly how)

They both end up in some html/js/css files.. and that will need to support switching to a different version somehow.

abjerner commented

The Angular and C# docs are now versioned and has been for a while - at least for the two latest major versions.

Is this sufficient? In which case we could close this issue (YAY).

Or should we strive to have versioned docs for each major minor? Or even patch releases? Or should the docs for a major minor version always be for the latest patch release for that major minor version?

If the docs only focus on the major version, it could very well contain something that wouldn't work in a previous release of that major version 😱

umbrabot commented

Hiya @abjerner,

Just wanted to let you know that we noticed that this issue got a bit stale and might not be relevant any more.

We will close this issue for now but we're happy to open it up again if you think it's still relevant (for example: it's a feature request that's not yet implemented, or it's a bug that's not yet been fixed).

To open it this issue up again, you can write @umbrabot still relevant in a new comment as the first line. It would be super helpful for us if on the next line you could let us know why you think it's still relevant.

For example:

@umbrabot still relevant
This bug can still be reproduced in version x.y.z

This will reopen the issue in the next few hours.

Thanks, from your friendly Umbraco GitHub bot 🤖 🙂