search

unixorn / awesome-zsh-plugins

A collection of ZSH frameworks, plugins, themes and tutorials.
BSD 3-Clause "New" or "Revised" License
15.18k stars 542 forks source link

An idea: Perl script to extract and commit plugins updated in the last 6 months #589

Open psprint opened 5 years ago

psprint commented 5 years ago

Hello! I was browsing the awesome list recently and had bad impression of old not-updated plugins that clutter it. This is a problem.

I thought: a Perl script could (a) download and parse awesome-zsh-plugins list via WWW::Mechanize, (b) extract the plugins that are contained in it and (c) again use WWW::Mechanize on each of the plugins' Github pages, to get the time of last commit.

So basically: filtering-out plugins that were updated in the last 6 months.

Then it becomes obvious: the README.md could have section "Active plugins" where the recently updated plugins would be listed. The README.md could be updated by the script automatically.

First version of the script could use git clone --depth 1 ... for the second step (getting time of last commit). It would be slow, but the main task would be to update README.md. So this reduces to a single basic WWW::Mechanize use and a few git instructions, and to builting the "Active plugins" section.

I could try coding this script, would it be accepted (it would be in this repo, via PR) and used?

PS. Another section could be build, "Mature plugins", where plugins with commit count >= 100 (or 50 maybe) would be listed.

unixorn commented 5 years ago

Rather than have people have to read multiple sections to find plugins, maybe have the script add annotation gifs to the entries in place?

psprint commented 5 years ago

I'm so disappointed about the quality of Zsh plugins that it would probably be the only section I would read. But I see your point. If doing a section, then it could consist of names/links-only, no descriptions. I also think the number of last-6-months updated plugins would be less than 10. But a gif that has a good visibility will suffice, Ok. I think that the list should really stand up because otherwise a sister page, with processed-only (recently updated, enough commits, maybe something else) plugin names has no restriction to appear.

I might approach the script. I rather mispointed the needed Perl module – instead of WWW::Mechanize some module for Markdown could be used. I could start now and if you will like the result, we could somehow integrate this with the README.md.

psprint commented 5 years ago

Turned out the task is so simple, that I've coded it in Zshell: https://github.com/zdharma/hacking-private/tree/master/zsh-plugin-assessor zpa

The script assigns 4 integers, e.g. for the alias-tips plugin, the score 2100, means:

Basing on those numbers I would tell that: the project is well time-invested and in maintenance mode (1, not 2 in the second score digit), and the author doesn't develop any feature or next-generation version in any branch. I find this very helpful, what do you think?

The script should be robust, well written, I wouldn't anxiously avoid it ;) Asciinema: https://asciinema.org/a/HKSm7GH4L5OyFX0xq3gk4R0QG

unixorn commented 5 years ago

This looks cool so far. I have a couple of suggestions:

unixorn commented 5 years ago

I want to be clear - I think this is a good idea, I'm just wrangling over implementation details now :-)

psprint commented 5 years ago

Progress detection

🚶- slow/moderate progress: 1 commit in each of last 3 months or 5 commits in total in 3 last months 🏃- fast progress: 3 commits in each of last 3 months or 10 commits in total in last 3 months

Attention detection

💤 - no update in last 6 months ⌛️- long time no update (updated not in last 3 months, but in last 6 months) ⏳ - updated in last 3 months, active ⏰ - updated in last month and month before it (single new commit will not yield it such a strong symbol like alarm clock; the additional criterion ("month before it") is to take into account only more constantly attended projects),

Research & development detection

💼 - has branches with at least 50 commits in total 📈 – the branches were active 3 times in last 4 months

Market-share detection

⭐️ - has 100 likes or more 🌟 - has 300 likes or more

I think the market share is an energy that makes the plugins act like dinosaurs – old, fossilized projects that get likes just because they have already much likes, i.e. dinosaurs among fresh energy projects. A way to handle this is single star symbol for not-high number of stars – this will even normal-popular projects with dinosaur-popular projects. But we can throw in a second star for 300 likes, it will work the same but less intensive.

I'm thinking about keeping the number score and creating a sub page with only "Plugins" section, that is sorted and shows the score. It would be a ranking. Note that the first number, 0, 1 or 2 for <=50, >= 50, >= 100 commits also works to even dinosaurs and normal projects, i.e. there is no extra score for 1000 commits. The activity then decides who is above who. I would extend the number-score to match some new ideas from the above emojis and any changes we will make.

jedahan commented 5 years ago

The star icon feels like a stronger positive indicator than anything else, even though I'd rather it not be.

There are so many different icons the readme will be hard to scan quickly - icons being clear outliers make things easier than trying to replicate all info we can get from git/github.

My proposal is that we incrementally add icons and see how it feels before adding more

Initially Iconography

Goals include reducing frustration when navigating to a new plugin and seeing it is unmaintained, and quickly being able to check a dozen likely useful plugins for a first-time zsh user.

📈 At least 3 commits to any branch in the last 3 months 💤 No updates in the last year ⭐️ Has 100 likes or more

As an aside, I personally believe in awesome lists being more curated than 'every link I can find', but I do appreciate that @unixorn includes new repos as that is super awesome.

psprint commented 5 years ago

I've noticed that I've forgot about commit count.

@jedahan: I write plugins for 3 years, in 2016 I've had ~8.7 commits per day, not excluding holidays, in 2017 it was 7.5 commits per day (Github profile can confirm this). Through this time I was observing how much work a well attended plugin receives, browsed the awesome-zsh-plugins list, looked for interesting plugins and inspirations. The conclusion was: my lack of daytime job results in high-commit count, and other plugin creators are most often throwing in 3-10 commits (often based on Bash-coding experience), posting announcement on Reddit, and that's it. It's not my intention to bash at them (that's why I mentioned my free time), but I would like to do something about this, to make Zsh plugins more software-like (that's why I've started but dropped Zsh 100 Commits Club). That's why I opt for commit count and activity to be main criterion. This way, if there would be a sorted plugin's list on a subpage, i.e. the ranking, then it would be dynamic, it would be interesting to look at it on regular basis. With stars-lead, the list will be fossilized with Zsh plugin dinosaurs, that are reaching any Zsh user anyway, through recommendations on IRC, reddit, etc.

psprint commented 5 years ago

@jedahan 'm not sure about your gradual-emoji-introduction proposition, I just don't know what to think about it yet, I must gain some insight. BTW. your geometry-zsh/geometry theme would get a very high rank, [2202], so it just looks that the research&development is fresh or that you delete merged branches.

psprint commented 5 years ago

The script was having commit-count and last-activity switched in places, plus one more bug. So for alias-tips, the score is [1200], for geometry it's [2222]. Commit count is first, but it is flattened – above 100 all have the same score.

Detecting devoted time or work

🥈 - has 50 or more commits 🥇 - has 100 or more commits

An experiment – how would alias-tips and some other plugins look like with the proposed rich-emojis approach:

I can tell that hand-crafting this data, i.e. establishing it, is a hell. The script can drop tons of burden from users.

jedahan commented 5 years ago

Sorry I was not clear - I agree with you that stars and watches are a bad metric for determining if a project is good or not, and that activity is most important. History is maybe second most important.

I like that we are using a script to decide, and think hand-crafting is a bad idea.

My new proposal is we use your script conservatively at first - only highlighting if a plugin is

An experiment – how would alias-tips and some other plugins look like with @jedahan proposed incremental-emojis approach:

Seems less exciting to read, which is a good thing - easier to pick out what is likely to be good and what is likely to be bad. Ultimately any work highlighting / lowlighting the list will be an improvement, and I thank you @psprint for maintaining and improving this list as a whole.

jedahan commented 5 years ago

Also https://github.com/zdharma/Zsh-100-Commits-Club/blob/master/Zsh-Native-Scripting-Handbook.adoc is super cool

psprint commented 5 years ago

I've updated the script, it generates the emoji string. It is the rich-set that I'm proposing, except I've removed 💤 , because it was cluttering view. I plan to re-add it for 1-year or 2-years inactive plugins.

Here is current awesome-zsh-plugins with the Plugins section added with the emojis:

https://github.com/zdharma/hacking-private/blob/master/zsh-plugin-assessor/README_new.md#plugins

I think it is cool, I've already discovered many projects as deserving attention, like you-should-use 🥇 🏃 ⏳, I think that 100 commits and fast commit pace do mean something. Or czhttpd 🥇 🏃 ⏰ – I read its code when wanting to complete Hacktoberfest, was very positively surprised by cleanness and overall quality – and now this has it's outcome in the emoji string, so I guess it's a good sign.

psprint commented 5 years ago

So I think that a thing can be now said about the two approaches – the compact one and rich one: compact symbols do not allow to detect precious, maintained, invested projects. The czhttpd is one example – I would predict that it's a long time inactive, learn-Zsh motivated project. With the gold medal, running man and alarm clock I can see that it's a well invested, very active project.

jedahan commented 5 years ago

Honestly I'd rather have anything with no icons be purged from the list, and everything else be on a wiki page. Normally I expect awesome lists to contain tools that are awesome instead of having to parse the whole thing and decide, and these icons help for that...

unixorn commented 5 years ago

I don't want to remove things for apparent inactivity or low commit count. Sometimes a plugin does one thing well already and doesn't need frequent updating, or was copied from a private repo and has had the history truncated.

Themes are very prone to being static - the author will get it looking the way they want and then there won't be any more commits.

psprint commented 5 years ago

Stable projects should be discoverable by gold or silver medal, my own projects have this property, e.g. ZUI library. Then author can do updates, even with the awesome-zsh-plugins in mind, to gain hourglass (this one is easy), I'm pretty sure that going back to a project after 6 months or 1 year easily yields 1 or 2 commits, I observe this, distance & clear mind quickly finds an amendment.

psprint commented 5 years ago

Just one more thing. Zsh plugins have a very bad reputation among upstream-Zsh people. One person that apparently looked at a few of them concluded that "they're of a very low quality", and I was agreeing with him, as I wasn't able to find even single one nice plugin on the list (370 plugins block out >= 10-20 interesting ones). The topic of upstream-default-plugin-manager appears from time to time, but almost nobody sees it being meaningful, needed. The Iconography allows to find plugins that actually work and this addresses the bad reputation and not-treating-serious issues.

0xdevalias commented 2 years ago

Necromancing this issue 4 years later.. but I was wondering if it might be simpler/easier to use one of the existing 'GitHub Readme Badge' type services that exist, such as:

That way the README itself wouldn't need to be kept up to date, as the badges would 'update themselves'.

For example, using https://badgen.net/#github it would be fairly easy to get something like the following for each project's GitHub repo:

eg. For https://github.com/zsh-users/antigen

This would also help to implicitly solve things such as:

unixorn commented 2 years ago

I can see maybe adding last commit and perhaps open PRs. I'm reluctant because it'll make the list look awful when the badging service has any downtime.

0xdevalias commented 2 years ago

For me personally, I would find the efficiency/productivity increase of being able to scan down the list and get the relevant information at a glance would trump the visual downside if the badge service had any downtime; which presumably is a pretty rare occurence, and even when it happens, would presumably not be for very long either. Essentially in my personal assessment, I weigh the benefits of something that will help most/all users, vs the unlikely/temporary scenario of there being downtime.

As for which badges I included above, the ones I chose were basically to allow a quick overview of the popularity of the project, when it was last updated, how much community activity there is on it, etc. Eg.

Ultimately I don't have a strong opinion on if/how you take on this suggestion, though I do think it would add a lot of valuable usability improvements to the project in a fairly 'low effort' sort of way.