search

tldr-pages / tldr

📚 Collaborative cheatsheets for console commands
https://tldr.sh
Other
50.21k stars 4.09k forks source link

rfc: update client specifications to accommodate mirrors #8284

Open SethFalco opened 2 years ago

SethFalco commented 2 years ago

Command description

This is mostly regarding this excerpt from the client specifications.

If appropriate, it is RECOMMENDED that clients implement a cache of pages. If implemented, clients MUST download the archive either from https://tldr.sh/assets/tldr.zip or https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/master/assets/tldr.zip (which is pointed to by the first link).

I, personally, do not think it's our place to suggest that we have authority over where clients or users choose to obtain a copy of tldr pages.

There are several reasons clients might want to change it up a bit:

In my opinion, we should change this wording to allow for or even encourage mirrors. Something along the lines of, the list of mirrors SHOULD include our official sources, but additional mirrors MAY be used for redundancy or for the user to select from.

End-users SHOULD have the means to switch mirror if they'd prefer to use another one. If their chosen mirror is unavailable, the client SHOULD retry the request with another mirror or fallback to the official source as set out by the specifications.

I think the metrics one would be a great privacy-friendly alternative for the following issue too:

While it exposed less information, it's entirely server-side, so users don't have code executing on their machines that isn't in their best interest.

sbrl commented 2 years ago

Another issue here to consider is the case of

  1. client developer creates mirror for their client
  2. mirror goes offline
  3. client is now broken.

...so if we allow mirroring in the spec, we should consider requiring clients that do support mirroring to have a priority-ordered list of mirrors. If 1 mirror breaks, then go down the list to find the next working one, finally ending on our official mirror.

Another issue here is the format of the pages in such a mirror. Currently we recommend clients download a .zip file we autocreate, but some clients clone the git repositories, etc. So it's unclear precisely what would be mirrored.

Finally, just to clarify for future reference here, this issue is very specifically about mirrors, and not about local repositories of custom pages.

SethFalco commented 2 years ago

Another issue here to consider is the case of

  1. client developer creates mirror for their client
  2. mirror goes offline
  3. client is now broken.

You basically just repeated what I said. This is the very issue I'm looking to solve by allowing mirrors. We shouldn't assume the only final solution is that people should fall back to our mirrors though, ours can go down just as much as any other.

In fact, there have already been times when most (if not all) tldr clients were broken at once. (Hence the issue with centralization I'm hoping we can resolve.)

Nothing wrong with what you said, I'm just trying to drive the point, we shouldn't consider our distribution any better than the distribution others may offer, which is what your wording gears towards.

CleanMachine1 commented 2 years ago

Where can we host these, because I doubt there will be too many contributor ones

I can think only think of gitlab tldr.sh, maybe a gitea

as my immediate thoughts.

While I can see the use case of wanting to not use github servers as a mirror, this will undoubtedly cause issues for the end user, depending on how it is added to a client.

marchersimon commented 2 years ago

What about all the organizations and universities, which also host linux distro images?

CleanMachine1 commented 2 years ago

Thats a good idea, some have mail to contact them.