Versioned protocol documentation with permalinks?

[jzwolak]

I’m updating Flask-Tus in a fork I made from the official Github repo. As I do so I see code that is clearly for certain sections of the documentation at tus.io/protocols/resumable-upload.html

I also found the documentation at transloadit.com/docs/

What I noticed are a couple things… it’s unclear what version of the protocol are being implemented and it’s unclear if the documentation for the protocol has been updated since the last updates to Flask-Tus.

Is there a versioned permalink to the Tus protocol documentation? Similar to how Python versions its docs - with the version number in the URL and the docs never change after that!

This would be incredibly useful for orchestrating multiple frontend and backend projects while maintaining compatibility!! If such a thing doesn’t exist, may suggest creating it

I’m wanting to reference the documentation with permalinks in the code so future maintainers know what each part of the code is implementing and can refer to the docs to both verify correct implementation and understand more what is going on.

Thanks!

[marius]

Hi Jason, apologies for my delayed response!

@jzwolak

it’s unclear what version of the protocol are being implemented and it’s unclear if the documentation for the protocol has been updated since the last updates to Flask-Tus

Implementations usually state explicitly what version of the tus protocol they support (e.g. v1.0.0), but I don’t see that in Flask-Tus’ README. That doesn’t really address your idea but I thought it’s worth to add here.

@jzwolak

Is there a versioned permalink to the Tus protocol documentation? Similar to how Python versions its docs - with the version number in the URL and the docs never change after that!

Not really, not on https://tus.io/. The closet you can get to a permanent link would be to link to the protocol at a specific commit at GitHub - tus/tus-resumable-upload-protocol: Open Protocol for Resumable File Uploads. That would work but is not really handy and nice, I agree.

@jzwolak

I’m wanting to reference the documentation with permalinks in the code so future maintainers know what each part of the code is implementing and can refer to the docs to both verify correct implementation and understand more what is going on.

Good idea, I like it a lot. Are you talking about having different URLs for each protocol version (currently there is only really v1.0.0 in use)? e.g. https://tus.io/protocols/resumable-upload/v1.0.0.html and https://tus.io/protocols/resumable-upload/v1.2.3.html?

However, I don’t want to make any promises here as our resources are somewhat limited and that honestly does not sound like a high priority to me.