search

tldr-pages / tldr

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

Removal of duplicated index.json from the generated ZIP archive, up-to-date clients tracking #2865

Closed mebeim closed 3 years ago

mebeim commented 5 years ago

As stated in #2862, I'm opening this to keep track of clients' compliance with the small change to the ZIP generation, that is, adding a top-level /index.json as replacement for /pages/index.json. Right now, both files are present since some clients rely on /pages/index.json to work, but the goal is to completely remove it and only keep the top-level /index.js.

As a consequence of this, I'm going to open issues on repositories of clients which rely on /pages/index.json being in the generated ZIP to alert them of the new change. Look at the bottom to see what I'll be mostly copy-pasting around for this purpose.

List of up-to-date clients

Checked box == up-to-date.

Text of the issue I'll be opening on client repositories:

Use the new index.json file in favor of the deprecated pages/index.json

Hello, I'm from the tldr-pages/tldr repository, and I'm here to inform you that we recently changed the content of the ZIP archive your client relies upon. Here's a link to the merged PR: #2862.

Inside the generated ZIP archive, a new /index.json file has been created, to be used in favor of the now deprecated /pages/index.json file, as you can see here. Once all the clients are updated, or enough time has passed, we will completely remove the /pages/index.json file from the generated ZIP archive, and only keep the top-level /index.json.

If your client does not rely on the mentioned file to work, you can close this right away, sorry for the trouble! Otherwise, in order to support the upcoming change, this client should be updated to either:

  1. Use the index.json file served by the static site itself, that is: https://tldr.sh/assets/index.json.
  2. Or use the new top-level /index.json file inside the ZIP file served by the static site, which is: https://tldr.sh/assets/tldr.zip.

Once the above is taken care of, you can close this issue and your client will be marked as up to date in our tracking issue here. This change should be trivial, but if there's any problem, please do let me know.

Thank you for your work and time you put into creating this client and supporting the TLDR pages project!

sbrl commented 5 years ago

Ah, great idea @mebeim!

Shouldn't the URL be https://tldr.sh/assets/index.json / https://assets/tldr.zip?

The client spec should probably be updated too. Could you open a PR for that please?

mebeim commented 5 years ago

@sbrl you're right about the URL, changed it. About the tldr.sh domain, should that be used instead of tldr-pages.github.io? I was unsure about which one to use.

As for the PR, well sure, once the above question is answered though, don't want to link the wrong domain :')

agnivade commented 5 years ago

Yeah, we can use tldr.sh. It is a CF front for tldr-pages.github.io.

mebeim commented 5 years ago

@agnivade noted, thanks.

owenvoke commented 5 years ago

Just a note, tldr-php and tldr-chrome don't use the ZIP file at the moment.

For tldr-php, we have BrainMaestro/tldr-php#6 and BrainMaestro/tldr-php#7 open for updating it to use the ZIP, so I guess when those are done, we can update straight to use this new file format. 👍

mebeim commented 5 years ago

@pxgamer If that's the case then those two clients can be already checked. Thank you. :+1:

mebeim commented 5 years ago

I looked around all client repositories and to my surprise I found out that very few of them use the /pages/index.json file inside the ZIP. Most of the clients directly request each page or directly clone this repo's main branch. Most of the clients which download the ZIP just browse it manually and maybe even build a different index by theirself. Others use the index file at tldr.sh/assets/index.json. I also saw a couple which just have a static local copy of all the pages, LOL.

So, basically as you can see I only had to open 4 issues (3 on GitHub, 1 on GitLab), of which one was already resolved and closed. This means only three clients with an open issue remain right now, and that one client which does not have a source listed anywhere for me to look into (though I believe it directly queries each page).

Pretty nice I'd say :nerd_face:

sbrl commented 5 years ago

Gosh! Interesting. It's actually in the new client spec that clients should be using index.json and the archives on tldr.sh :thinking:

owenvoke commented 5 years ago

I'm not sure it would be possible for the Chrome extension. But for the PHP client, I might make a PR when I'm back home.

mebeim commented 5 years ago

@pxgamer well I don't think that the spec should be taken that literally for every client. Clearly it is a good guideline to follow, but doesn't fit all scenarios.

sbrl commented 3 years ago

Just sent an email to DistroWatch's contact email address, just in case.

sbrl commented 3 years ago

Update: They've replied with the following:

Thanks for letting us know. We actually pull directly from the git repository to get new page versions, but I appreciate knowing the index file has moved.

All the best, Jesse

Looks like DistroWatch is absolutely fine, and we don't need to worry about them. I've updated the list in the original issue.

bl-ue commented 3 years ago

Nice! Thank you @sbrl.

bl-ue commented 3 years ago

Should I have kept this open until all clients are okay @sbrl?

mebeim commented 3 years ago

I think this is fine as is. We used this to mainly track clients before applying the change. It was useful before as an indicator to know if or how much we needed to wait, but now that the change is applied, keeping this up until the last client updates their code does not really have any advantage.