Inactive and unmaintained clients

[ivanhercaz]

In Gitter arise an issue very interesting about the maintenance of the tldr-pages clients lists, "lists" rather than "list" because we have two lists, one in the README and another one in a wiki page. The user @principis address this issue asking about if someone should clean the clients lists, and after a conversation with @sbrl and me, we agree it would be interesting to address it.

The original message of @principis is the next:

Should someone look into cleaning up the clients list? For example the TLDR Elixir Client is 6 years old, archived and still says "(binaries not yet available)". There are probably more clients which aren't being updated and/or following the client spec.

Recently I announce that I began to work in an Elixir client. The main reason I began this project is because the TLDR Elixir Client was inactive, archived and its development does not seem to continue (check TLDR Elixir Client repository).

There are probably another clients in this situation: inactives officially, like the TLDR Elixir Client, and apparently inactive or unmaintained. This second category seem a bit more subjective, but it probably needs a review.

Some questions to think about this issue may be:

• What should be the criteria to keep a client in the list?
• Should we accept any client in the list? Or just the ones which accomplish with client specification?
• Should we consider the time without activity in the repository? By development? By important issues without activity?

[ivanhercaz]

I am going to answer in a comment the above questions:

What should be the criteria to keep a client in the list?
I think this is the key of this issue. If we decide to clean the lists we should establish a criteria in which we would use to substantiate the decision. Now I have not a clear answer, thus I think this issue is useful.

Should we accept any client in the list? Or just the ones which accomplish with client specification?
Accomplish with client specification might be a good point to start. This even affect me, because ExTldr does not accomplish with the client specification and in this case it would not be in the client lists. But being honest, I think it is an objective criteria based mainly in the fact that if a client accomplish with the latest client specification or have backward compatibility, it should be in the lists.

Should we consider the time without activity in the repository? By development? By important issues without activity?
Sometimes the time without commits or releases is not a fact to drop something, because the reason may be that the client is already fine and it does not need any other change in its source code. In the other side, sometimes it may indicate lack of maintenance or inactivity of the project even if the repository is not archived. This is more obvious when the client repository has important issues without responses by the maintainers or possible solutions, or even pull requests stacked without being reviewed.

Of course, if a client repository is archived, I think it should not be in the lists. It does not mean only inactivity, but lack of continuation of the project too.

[zlatanvasovic]

This definitely should be implemented, but I'd keep a list of inactive/archived clients somewhere too.

[sbrl]

This is an excellent issue to raise.

I think that compliance with the client specification might be a good place to start. What about if a client hasn't made progress in conforming to the client specification in 6 months, then it's classed as old / unmaintained? We could have a second list of clients below the primary list that contains the old / unmaintained clients.

[ivanhercaz]

Totally agree with both of you, @zdroid and @sbrl. It would be interesting to keep a list of old/unmaintained/inactive/archived clients, although I will put a warning note in the top. This list could be only in a wiki page.

What about if a client hasn't made progress in conforming to the client specification in 6 months, then it's classed as old / unmaintained?

That seems a really interesting option. If someone propose to add a client to this repository, but it does not accomplish with the client specification, but there are users working on the task, it should be enough.

Of course, this requieres for our part to review every X months if the clients still accomplish the client specification or if there have had progress with the client specification accomplishment.

[sbrl]

Of course, this requieres for our part to review every X months if the clients still accomplish the client specification or if there have had progress with the client specification accomplishment.

True. But I guess any option here requires regular review.

[principis]

I think regular review shouldn't be required in the sense that, if a client supports the current specification it'll probably be fine for a while. On the other hand, every change to the client specification should be checked against the clients.

[MasterOdin]

Alternatively, could make it so that the list of clients is done with categories of specification supported, and put the onus on the client authors to make sure their client is in the right place on the list. For something like tldr, at a certain point, there's a good chance a client could be "done" for a given version that no further updates happening on it isn't a sign of "unsupported", just that there's nothing to be accomplished. Even an archived one is "unsupported", but if it is accomplishes everything in say spec 1.1, what does it matter?

A fun idea would be also that one could in-theory every time a client specification update happens, make a release on this repo, and have a github action workflow get triggered to run through the list and post an issue on each client's issue tracker that a new spec version has been released, and to update their client, and then to bump it in the list of supported clients.

[principis]

@MasterOdin The problem is, if no further updates are happening, it will mean that when a new client specification comes out (for example for the future page layout change), the client will be unusable.
I don't completely understand your category system. Because if 2.0 comes out, 1.2 clients probably just won't work anymore.

A fun idea would be also that one could in-theory every time a client specification update happens, make a release on this repo, and have a github action workflow get triggered to run through the list and post an issue on each client's issue tracker that a new spec version has been released, and to update their client, and then to bump it in the list of supported clients.

Something like that seems like a great idea. Maybe not with a release, because there currently are none and it may confuse people.

[principis]

Simple table with every client:

Client	Status	Supports spec 1.2
Alfred Workflow
Albert Plugin	Recent commits	N/A?
tldroid
tldr
tldr-bash-client
C# client	supported	yes
C client
Chrome Extension
Crystal client
Dart client
Dash docset
tldr-docker
ExTldr.	developing	in progress
TLDR Elixir Client	Archived
Emacs client
github.com/pranavraja/tldr
4d63.com/tldr
github.com/elecprog/tldr	supported	partially
github.com/isacikgoz/tldr
tldr-man-page
tldr-pages
Haskell client
Node.js client
OCaml client
Perl5 client
PHP client
tldr-python-client
tldr.py
R client
Ruby client
Rust client
Vim Client
Visual Studio Code extension
tldr.jsx: http://tldr.ostera.io/
DistroWatch
tldr.ooops.me

I don't have time to test a lot of clients, but I filled in some I know.

[MasterOdin]

@MasterOdin The problem is, if no further updates are happening, it will mean that when a new client specification comes out (for example for the future page layout change), the client will be unusable.

Maybe. For example, clients that support client spec 1.1 should still work just fine under 1.2. If the spec goes from 1.2 -> 2, then yeah, clients may break. However, I think for that, just wrap the wording on the page so that you've got "Clients that support Specification " and then a line divide, and a note being like "Clients under here conform to an older version of the specification. As such, they may or may not work." and then continue on with "Clients that support Specification ", etc. Of course, this can get a bit wordy, so would probably move this into the wiki or something and not in the README?

This is more of just a way to make it less onus on the tldr organization to keep abreast of all clients, and put it on the client developers themselves.

[sbrl]

We could even fill in which client spec version clients support? But that might be too much work.

I really like the idea of automatically opening an issue when we make a release on this repo / update the client spec. That seems like a great idea!

[ldorigo]

Please, yes. As an end user I really don't care what my client is written in or to have 25 different options. I want an easy, functional way to install and access tldr pages.

[bl-ue]

I know no one probably is going to agree with this :), but I always have thought and do think that we shouldn't have a "Node.js" client or "Python" client but a "CLI" client, and a "Keypirinha" client, and a "web" client, etc. Of course, it's much easier said than done, but having fewer clients makes it easier to make big changes such as #4120.

The issue with this too, is that those clients are community maintained. If we had a "CLI" client etc. like I'm proposing they would have to be official, i.e. part of the tldr-pages repo. If we had one client per type, so one client for CLI (preferably in Go since that's common for that type of tool :) ), and we had to maintain them ourselves, it would likely be a lot less work than to deal with worrying about breaking 25 community maintained clients, issues pertaining which one to choose, etc.

[sbrl]

@bl-ue that's an interesting idea, but even within the idea of a CLI client you'll have a job developing a universal client that works on all platforms: Windows, macOS, Linux, BSD, Solaris, Haiku, .... the list of OSes goes on an on. And with Go you also have to worry about CPU architectures. This page is a favourite reference of mine for that. So I think there are definite advantages to having lots of different clients.

[bl-ue]

@sbrl

TL;DR It would be nice to at least reduce all of the CLI clients into a single, official one. I think probably the vast majority of users use the CLI version anyway, and are rather confused by the plethora of options.

1. Does the tldr client need to be supported on any other platforms besides the major ones, which Go supports? Most tools, including most tools documented in this tldr repo, don't support any other OSes.
2. If some people do use those operating systems, how likely is it that they would ever use tldr on them?
3. Why does the tldr client need to run on operating systems that many other tools don't?

And with Go you also have to worry about CPU architectures.

That's a good point, but Go does support several of the architectures listed on that page you linked, see https://blog.golang.org/ports.

So I think there are definite advantages to having lots of different clients.

I think so too, but not necessarily because of the OS/arch issue. We need clients for iOS, Android, Web, Vim, Docker, Keypirinha, etc., and I don't really see any way to have tldr in those environments without multiple clients.

But the fact that we have so many CLI clients for such a simple documentation source and having to watch them seems to me impractical.

@ldorigo wrote:

As an end user I really don't care what my client is written in or to have 25 different options.

which I agree with and have though the same thing since I realizd that there were multiple CLI clients. The tldr-pages organization actually has 4 different CLI clients that all serve basically the same purpose!

@ldorigo was actually very accurate when he said 25 clients, because I looked and the readme and parsed out 24 different CLI clients...

[sbrl]

You raise some good points. We do have a reference client in Node.js over in the tldr-node-client repo. But writing a new client requires lots of effort and work - and also programmers with skills in Go for example if Go were to be picked.

In my opinion, I think it's far too late to change what's already happened.

Despite this, there is room for improvement. Some way of tracking compliance with the client spec would perhaps be useful, and keeping track of which clients support the latest version of the client spec. Notifying client authors about updates to the spec would be very useful too.

[MasterOdin]

There may be value though in at least having the major package managers of the big distributions / OS all use the same client though (which is ideally maintained by tldr?). A quick look at the ecosystem:

OS	tldr client
Debian	https://github.com/psibi/tldr-hs
macOS	https://github.com/tldr-pages/tldr-c-client
arch	https://github.com/tldr-pages/tldr-python-client
fedora	https://github.com/tldr-pages/tldr-python-client
Chocolatey	https://github.com/isacikgoz/tldr

[mflint]

Simple table with every client:
Client Status Supports spec 1.2
tldr-pages

This is client for iOS.
Supported: yes
Supports spec 1.2: no (I really should do that)

[sbrl]

@mflint if you have any queries when you're working on implementing the new versions of the spec, do get in touch! We'd love to help. Quick link to the client spec changelog for convenience: https://github.com/tldr-pages/tldr/blob/master/CLIENT-SPECIFICATION.md#changelog (we're on v1.5 now, but the versions in between are relatively minor changes)

[bl-ue]

There may be value though in at least having the major package managers of the big distributions / OS all use the same client though (which is ideally maintained by tldr?). A quick look at the ecosystem:

OS	tldr client
Debian	https://github.com/psibi/tldr-hs
macOS	https://github.com/tldr-pages/tldr-c-client
arch	https://github.com/tldr-pages/tldr-python-client
fedora	https://github.com/tldr-pages/tldr-python-client
Chocolatey	https://github.com/isacikgoz/tldr

I completely agree with this. In my opinion, an official client written in an interpreted language conflicts a lot with this goal, because in order to run the client Node.js, Python, etc. has to be installed

That's why I was advocating for Go (#4044 (comment)). In my opinion, Go is not difficult to learn, being similar in many ways to common languages like JavaScript and Python. In fact, of all of the languages that I've learned (which is several), Go has been the easiest for me to learn. For most software developers learning Go should be a simple task.

The other benefit of Go is that it compiles to a single binaries for AIX, Android, Darwin (macOS), Dragonfly, Illumos, iOS, Linux, NetBSD, OpenBSD, Plan9, Solaris, Windows (and many different architectures for each), with no depencies or runtime necessary for running (and one unique thing about Go is that you can compile a binary for any platform from any platform, e.g. create a .exe for Windows on macOS 😉). It's not a runtime and text source code bundled together into with a wrapper, like you might do with Python or Node.js. It's actually compiled (albeit the binaries are a bit larger, e.g. a "Hello World" C program is 12 KB while a Go one is 1.3 MB. The terraform binary is only 73 MB, smaller than most LLVM binaries.)

Supported Go target platforms

$ go version
go version go1.16.2 darwin/amd64$ 
$ go tool dist list
aix/ppc64
android/386
android/amd64
android/arm
android/arm64
darwin/amd64
darwin/arm64
dragonfly/amd64
freebsd/386
freebsd/amd64
freebsd/arm
freebsd/arm64
illumos/amd64
ios/amd64
ios/arm64
js/wasm
linux/386
linux/amd64
linux/arm
linux/arm64
linux/mips
linux/mips64
linux/mips64le
linux/mipsle
linux/ppc64
linux/ppc64le
linux/riscv64
linux/s390x
netbsd/386
netbsd/amd64
netbsd/arm
netbsd/arm64
openbsd/386
openbsd/amd64
openbsd/arm
openbsd/arm64
openbsd/mips64
plan9/386
plan9/amd64
plan9/arm
solaris/amd64
windows/386
windows/amd64
windows/arm

Of course, you couldn't use a Go binary for a Web client (althought you can compile a Go program to JavaScript for WebAssembly), and you couldn't conveniently and conventionally write a Go iOS UI. But Go has excellent community support for all kinds of CLI needs (e.g. the very popular CLI argument parsing library cobra), and of all of our CLI clients, the largest amount written in a single language is Go, as we have 4 Go clients.

These are just my thoughts.

[vladimyr]

I completely agree with this. In my opinion, an official client written in an interpreted language conflicts a lot with this goal, because in order to run the client Node.js, Python, etc. has to be installed

Keep in mind that as long as clients are installed using respective package managers those runtimes might get installed automatically due to being listed as dependencies. Also in the world of Linux and macOS Python is already there.

with no depencies or runtime necessary for running (and one unique thing about Go is that you can compile a binary for any platform from any platform, e.g. create a .exe for Windows on macOS ).

It's actually compiled (albeit the binaries are a bit larger, e.g. a "Hello World" C program is 12 KB while a Go one is 1.3 MB.

That holds true from a regular user's perspective but isn't technically correct. Go binaries are rather large exactly because they bundle (statically link) that missing runtime. FWIW cross-compilation is very easy with golang but most certainly isn't unique to it.

With that being said I fully agree that golang is a very practical choice in regards to getting things up and running quickly. 👍

[sbrl]

Given the way the Debian folks package Go stuff, it might actually be a bad idea. From my (very limited) experience, they seem to package Go stuff like C binaries - i.e. dynamically linked to library files.

Despite this, I'd suggest that the client we pick for this @bl-ue is not the "one and only client", but one of our "reference clients", though even here that doesn't completely resolve the issue of unmaintained clients, because someone who knows Go would have to make a long-term commitment to keep it updated. I'm still absolutely against dropping the current community-maintained clients for all the same reasons I explained before.

Having said this, It does make sense that the single client is chosen to fulfil the role for every default package in package managers. Rust or Go or X language here would all be good for different reasons, but thinking about maintainability I would suggest that we pick a client that:

1. Is written in a language that lots of people know already, so that it's more statistically likely to be maintained
2. Is easy to package for all the target platforms.

Although my Python is rather rusty, I'd perhaps suggest that the Python client would be the best fit here, since some form of Python is installed by default on most systems.

Whichever client is picked, we'll want to review their compliance with the spec, and open issues / PRs to fix any issues found (might want to do this anyway with the existing reference clients).

[bl-ue]

Agreed—Python is good and simple but not installed by default on Windows :/

Rust I'd definitely say no to because it's not that intuitive to learn—Go on the other hand it quite easy to learn as it really borrows from Python/JavaScript a lot, and has "pointers" but not really C-style pointers, you can't use pointer arithmetic with them; they're mostly equivalent to references in C++, and I'd say passing a variable by reference vs. by value is pretty obvious (once explained) to any developer.

I'm still absolutely against dropping the current community-maintained clients for all the same reasons I explained before.

After a little more time spent with the project I've come to this view as well and I no longer advocate for the approach—say we do get a good language picked out and a nice official CLI client written...what about web, Android, iOS, etc.?

[bl-ue]

Back to the point—I'm compiling a detailed table of all of the clients listed on the readme and whether or not they're maintained and whether or note they support pages that use non-English punctuation (e.g. a Chinese colon at the end) for #5240. I'll post it here when I'm done and then we can trim off the unmaintained ones.

[vladimyr]

@sbrl I follow your reasoning here but I would like to add that if there are multiple good candidates from a maintenance perspective, we should favor the one that is best from the user's perspective i.e. fastest. I'd argue that both Python and Node tick the former box but let's see how they compare in regular workflows using something like this for instance: tealdeer-rs/tealdeer#129 (comment)

[vladimyr]

Rust I'd definitely say no to because it's not that intuitive to learn—Go on the other hand it quite easy to learn...

I understand the sentiment and personally find golang easier to work with but let's be objective. This is pretty much a biased statement 🙃

[MasterOdin]

Agreed—Python is good and simple but not installed by default on Windows :/

Python 3.5 is also not installed by default on macOS and maybe a number of LTS Ubuntu releases if we want to get pedantic. However, I disagree on that being a disqualifying criteria as installing the right version of python is extremely straight forward (same as node).

Additionally, using the benchmark above for it:

→ hyperfine 'tldr tar'
Benchmark #1: tldr tar
  Time (mean ± σ):      96.5 ms ±   5.9 ms    [User: 69.9 ms, System: 21.9 ms]
  Range (min … max):    86.4 ms … 113.6 ms    25 runs

→ hyperfine 'man tar'
Benchmark #1: man tar
  Time (mean ± σ):     103.7 ms ±   4.6 ms    [User: 100.9 ms, System: 19.1 ms]
  Range (min … max):    96.2 ms … 117.5 ms    24 runs

So 30ms behind tealdeer and faster than man, seems fine to me on speed.

At the end of the day, I would argue the only real criteria of choice is purely on what do the most community maintainers prefer for a language. If only one person wants or knows rust and writes a client in rust, then god forbid they ever leave. Going from JetBrains' Dev Ecosystem Survey, JS and Python are good choices versus Go, but as @bl-ue indicates, Go isn't too bad on learning, but it's not clear to me that the majority of maintainers current work with it / know it.

[vladimyr]

@MasterOdin Factual, nuanced, practical. 💯 👍

[sbrl]

@bl-ue see my comment here regarding utf-8 support in clients.

[bl-ue]

Everyone, please see #6163. It's my first big step towards pushing this issue and the problem regardling clients in general to a close. I'd appreciate some input there.

I'm thinking that opening the issue(s) on a release is the best approach. GH notifications are very light and ephemeral-ish, while issues are very clear and noticeable. They also don't rely on the user watching our repository for releases.

We still need to decide on opening one issue here or one issue on each client's repo. For reasons I stated in #6163, I prefer the former.

[sbrl]

Oh, automatically opening an issue against client repos on releases with a summary of changes sounds like a great idea! Then client authors can close the issue when they've implemented the new features.

[xiongchiamiov]

Fyi, right now I think as a result of this discussion, the readme starts a chain of broken links. The readme has

There are also various other clients provided by the community, both for the command-line and for other platforms. For a comprehensive list of clients, head over to our Wiki.

which is a non-existent wiki page. There is https://github.com/tldr-pages/tldr/wiki/Minimum-specifications-for-tldr-pages-command-line-clients , but that says the long list of clients is in the readme and links back to the section that says they're in the wiki.

If the decision about how to store them is pending, then probably all these references to a list existing should probably be cleaned up so new folks are confused trying to find a list that doesn't exist.

[MasterOdin]

@xiongchiamiov This has been fixed and the wiki page restored. Not sure why @Metolinam did this?

commit 368c76b16f957d1dad5a0ccf3924b5cec5659aa8 (HEAD -> master, origin/master, origin/HEAD)
Author: Metolinam <103972608+Metolinam@users.noreply.github.com>
Date:   Thu May 26 20:44:29 2022 +0300

    Destroyed tldr pages clients (markdown)

[Managor]

Closing this as there doesn't seem to be any issues with the clients page. Please reopen if you disagree.

[kbdharun]

@Managor The conversation here isn't just about listing the clients on the client page alone it is about how we handle inactive and unmaintained clients that follow old client specifications (and aren't archived). IG we can continue the conversation in #10133 since some points are already addressed.