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

[psprint]

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]

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]

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]

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

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

• 2 - there are >= 100 commits (1 is for >= 50 commits),
• 1 - project was updated within last 6 months (2 is for: last 3 months),
• 0 - there are <= 50 commits in all branches counted together
• 0 - there was no branch update in last 6 months

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]

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

• Use icon gifs for each category instead of a number. It's easier for people unfamiliar with the system to understand that "Plugins with a calendar icon have been recently updated, plugins with a X icon have had > 50 commits" than to remember that the second digit of the code number tells me it has been recently updated.
• Maybe have it scrape the GH API to get star counts for the plugins and use gold/silver/bronze stars to represent how starred a plugin/theme is? Or even just have a star icon with the number of stars. The more stars, the more likely the plugin is to be good/useful.

[unixorn]

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

[psprint]

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]

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]

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]

@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]

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:

---

• 256color 💤 - Enhances the terminal environment with 256 colors. It looks at the chosen TERM environment variable and sees if there is respective ncurses' terminfo with 256 colors available. The result is a multicolor terminal, if available.
• alias-tips 🥈 ⏳ ⭐️ - An oh-my-zsh plugin to help remembering those aliases you defined once.
• wakatime-zsh-plugin 💤 - Track how much time you have spent in your terminal. Has per project stats.
• wakatime 💤 - Automatic time tracking for commands in ZSH using wakatime.
• geometry 🥇 ⏰ 💼 📈 🌟 - A minimal ZSH theme based on Avit and Pure that displays a lot of git information and is composable and customizable.
• zhooks ⌛️ - Displays the contents of any ZSH hook arrays and the code of any hook functions that have been defined. Useful for debugging.
• fast-syntax-highlighting 🥇 🏃 ⏰ 💼 - Optimized an improved zsh-users/zsh-syntax-highlighting – better response times, zed/vared can edit 10 kB functions.
• zshmarks 🥈 💤 - A port of Bashmarks (by Todd Werth), a simple command line bookmarking plugin, for oh-my-zsh.

---

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]

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

• 📈 active (3 commits in last 4 months)
• 💤 inactive (0 commits in last 12 months)
• 🌱 new (<15 commits on main branch)
• 🌲 experienced (>100 commits on main branch)

---

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

• 256color 💤 - Enhances the terminal environment with 256 colors. It looks at the chosen TERM environment variable and sees if there is respective ncurses' terminfo with 256 colors available. The result is a multicolor terminal, if available.

• alias-tips - An oh-my-zsh plugin to help remembering those aliases you defined once.

• wakatime-zsh-plugin 💤 - Track how much time you have spent in your terminal. Has per project stats.

• wakatime 💤 - Automatic time tracking for commands in ZSH using wakatime.

• geometry 📈 🌲 - A minimal ZSH theme based on Avit and Pure that displays a lot of git information and is composable and customizable.

• zhooks 📈 - Displays the contents of any ZSH hook arrays and the code of any hook functions that have been defined. Useful for debugging.

• fast-syntax-highlighting 📈 🌲 - Optimized an improved zsh-users/zsh-syntax-highlighting – better response times, zed/vared can edit 10 kB functions.

• zshmarks 💤 - A port of Bashmarks (by Todd Werth), a simple command line bookmarking plugin, for oh-my-zsh.

---

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]

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

[psprint]

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]

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]

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]

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]

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]

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]

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:

• https://github.com/badges/awesome-badges#dynamic-badge-services
• https://badgen.net/
  • https://badgen.net/#github
  • https://github.com/badgen/badgen.net
• https://shields.io/
  • https://shields.io/category/activity
  • https://shields.io/category/issue-tracking
  • https://shields.io/category/version
  • https://github.com/badges/shields

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:

• Outdated stuff #1415

[unixorn]

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]

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.

• Commit time, latest release/tag, and number of releases can help show how it's updated/when that last was
• Lots of stars/forks can indicate popularity
• Lots of open issues/PRs can imply that it's not well maintained
• Having many contributors can imply that it's not just a single developer maintaining it (and the associated risks of it becoming unmaintained)
• etc

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.