User stories for a community plugin library

[Jermolene]

There is broad agreement in #5392 that the most valuable initiative for the TiddlyWiki community in 2021 would be the provision of a community plugin library (CPL).

Before we can discuss how we might implement the CPL we need to discuss and agree the requirements. I propose that we take a disciplined approach, and focus in the first instance on collecting and validating "user stories".

User stories are a simple convention for capturing requirements that has proven to be an effective way to build a shared understanding. It's a simple convention that encourages clarity and helps to draw out any implicit assumptions. I'd recommend this guide for an overview: https://www.gov.uk/service-manual/agile-delivery/writing-user-stories

An example of a user story might be: "As an end user, I want to be notified that updates are available for my installed plugins so that I am always running the latest greatest versions".

I suggest that each user story be a separate post, with the key sentence in bold as above.

[NicolasPetton]

As a plugin developer, I want the plugin library to update my plugins automatically each time a new release is out so that end users can upgrade straight away.

Another point for having a plugin library that updates the plugins automatically is that if we rely on some human action to update plugins, the plugin library will inevitably be lagging behing, and plugin developers might prefer to publish their plugins in their own library that will always be up-to-date.

[Jermolene]

Does this assume that the plugin developer has a dedicated URL for publishing released versions of their plugins? And that intermediate, under-development versions of their plugin would never appear at that URL?

In which case, surely there has been a "human action" when the developer decided to push to published URL?

[NicolasPetton]

In which case, surely there has been a "human action" when the developer decided to push to published URL?

I meant human action from the library maintainers/curators. As a plugin developer, I do not want to have to wait for someone to include an update of my plugin.

[NicolasPetton]

Some plugins might not even have release cycles and under-development versions.

[linonetwo]

Yes, we can have this. Use https://github.com/tiddly-gittly/tw5-plugin-packer action to publish JSON to release when you tag a git commit (feature of gh-action).
And you can get its link like https://github.com/tiddly-gittly/tiddlywiki-plugins/releases/latest/download/24.3A.2Fplugins.2Flinonetwo.2Fservice-worker.json

[linonetwo]

We use this to update https://github.com/tiddly-gittly/TiddlyWiki-CPL , so plugin developer can just add tag in their own repo, and then release -> cpl update -> user gets update will automatically happen. No even need to update version number in the CPL.

[twMat]

As an end user, I want a consistent presentation for all presented plugins (etc) so that I don't need to "think" in order to install the plugin.
I.e all creations should show in the same way, at least on a category level i.e all plugins provide "this and this" information, all "tips'n tricks" follow a specific format, etc.

Implementation wise I'd guess this means either agreeing on conventions or forcing the developers to use some template or match some kind of API.

[twMat]

As an end user, I want the presentation of the plugins (etc) to provide access to dedicated community discussion about the plugin so to get a feel for the plugin (its quality, its development status and issues etc).

"Access" could be simple links. But the main point are dedicated community discussions so important data about the plugin is not scattered in more than a few "threads" (or however it is manifested). It makes sense with multiple dedicated discussions (e.g "development issues", "installation questions", "suggestions" etc).

[twMat]

As an end user I want the "typical appstore meta-data" to be readily seen in the library, for a quick impression.

This relates to both of my previous descriptions; I refer to e.g a quick description, rating, perhaps reviews, etc.

[twMat]

As an end user and as a developer, I want the community to be able to categorize the plugin so to show what other plugins/stuff it relates to.

This is a very big deal. If the cummunity can arbitrarily add e.g tags, then there would probably be a need for some kind of "ranking" of the tags (e.g possibility to "vote/agree" with existing tags so that they are more prominent). Example of such tags could be anything, e.g "editors", "prettification", "GTD"...

[twMat]

As a plugin developer, I want the "upload process" of my plugin/update to consist of as few steps as possible. E.g "create a plugin, click a button and it's done".

Maybe it's beyond the scope of the matter, but if I didn't have to package it as a plugin first then that's even better. I.e I select the tiddlers that the plugin consists of and just send them off.

[twMat]

As a user I want to easily take part of developer notifications

For example, in my listing of installed plugins there could be a subtle icon change like the notification icon here in gh. Opening a special tab inside the plugin shows the message.

[saqimtiaz]

As a plugin developer, I want any dependencies (other plugins) to be installed automatically when a user installs my plugin.

The dependency might be another plugin of my own, or a plugin by a different developer that is published in the same library.

[saqimtiaz]

Related but not really just about the CPL:

As a user I want the list of installed plugins to indicate, which plugins are required by other plugins.

[saqimtiaz]

As a user and as a plugin developer, I want any associated release notes or introductory information/usage guide to be displayed after a plugin is installed.

However this should be user-configurable during the installation process.

[pmario]

As a plugin author I would like to be able to provide language-specific text-packs for 1 or more of my plugins

[pmario]

So 1 text-pack should be for 1 plugin. Or 1 bigger pack should contain all texts that my plugins use

[pmario]

As a user I want to load language-packs for plugins, that are treated as AddOns for the core languages

[pmario]

So if I switch the core language, I want, that the language switcher extracts the core lang-tiddlers and ALL other lang-addOns

[NicolasPetton]

That would be great (and I really miss such a feature currently in TW), but IMHO it's ouf of the scope of a community plugin library.

[kookma]

As a plugin developer, I want any dependencies (other plugins) to be installed automatically when a user installs my plugin.

[morosanuae]

As a user I want to be notified when there is a new version of a plugin available through some news-feed mechanism.

[TiddlyTweeter]

@morosanuae

As a user I want to be notified when there is a new version of a plugin available through some news-feed mechanism.

Right. Reading through the comments my overall impression is that an AGGREGATOR could solve a lot of the issues raised?
Fact is most of of our resources are disparate, all over everywhere.

Some mechanism to "auto-trawl" flagged resources or creator/updater "flags for re-trawl" seems not irrelevant?

[morosanuae]

As a user I want to get in touch more easily with the developer of the plugin, to ask for help, report bugs or suggest improvments.

[morosanuae]

As a plugin developer I want to get in touch more easily with the user of my plugins and to be notified by mail when there is a new message posted regarding one or more of my plugins.

[OdinJorna]

As a user I want to have an easy way to test and try out a plugin before installing it into my wiki.

[pmario]

Hmm, That's usually, what demo pages are for.

[AnthonyMuscio]

Firstly
Actually you can use a publicly available playground wiki, with local storage to test a plugin, typically against a copy of tiddlywiki.com so you have a lot of content to test against try mine https://anthonymuscio.github.io/playground.html

But I feel one should be prominently documented on tiddlywiki.com

Secondly
Another approach is to use a custom version of the inner wiki plugin to spawn a copy of the current wiki but also include the additional plugin to see the result and interactions. Perhaps unwise on a large wiki, however in this case just clone the tiddlywiki html file and test on that (This is the current method already available to anyone)

Thirdly
There is a method by which to call an online wiki with a payload of additional tiddlers such as a plugin. I am not sure if there is a reload issue but this could be refined to assist with the original suggestion.

[pmario]

As a user I would like to have prominent links to demos and docs

[twMat]

I don't know if this is beyond the scope of a CPL but...

As a user, it would be neat if I could download a complete TW via the library, i.e an empty TW with or without additional selected plugins installed - and - that I can also select tiddlers from my current wiki to come along.

This would make it very easy to quickly spawn custom wikis, both for mere testing/evaluation and sharp ones. In contrast to merely fetching a plugin, I assume the "output" here would have to be downloaded.

[hoelzro]

Not a user story, but I came across #3102 while looking through the issue tracker, and thought it might be handy to link that into this discussion!

[neumark]

As a user, it would be really nice to have some information on what a plug can / cannot do. I understand that there are technical as well as philosophical questions wrt how sandboxed a plugin should be, but it's scary to install a plugin known that it could delete all tiddlers (for wikis hosted online, it could potentially far worse).

[twMat]

OP reads

collecting and validating user stories

Does this mean the next step is the "validating" part? Or maybe the validation is already in process hereabove i.e the comments to the posted stories here above? How do we know when we're ready for a next step? And what step is that?

(I just polished up a plugin I made long ago so it could potentially be published to the community. I'm sure it would benefit a lot of people.)

[TiddlyTweeter]

This is an interesting discussion! I have ONE problem with it: trying to grasp the SCOPE. What I mean is we not talking about "all and everything" ... but some method to VALIDATE a finite set of entries and then PRESENT them??? They seem like quite different aspects of the issue: validate & present?

"Presentation" looks a bit complicated. I mean, if you had 100 entries, HOW would you enable a user to find ONLY those most relevant to their needs?

Just thoughts, TT

[manunamz]

This isn't a user story, but I wanted to drop a link to the TiddlyWiki Toolmap in case those who don't know it exists are reading this thread. (The contrast might help with defining user story definitions)

[MartyGentillon]

As a user, I want to know where all the plugins I have installed came from, even if that isn't a plugin library.

[pmario]

The place where you downloaded my plugin, may not be the "original" site. So in no way I would want that my plugins are linked to 3rd party pages, where I don't have control.

[saqimtiaz]

Not to mention that due to security consideratons, browsers don't expose this information when dragging and dropping plugins between wikis.

[twMat]

The community plugin library could offer a separate metadata tiddler to download along with the plugin. This metadata could be modified/curated by the community. The local plugin library presentation of the plugin could present this metadata.

[MartyGentillon]

@saqimtiaz I was afraid that would be the case.

Incidentally, that implies that we may want to provide a way to install non-library plugins by pasting a url someplace so that information can be recorded.

[MartyGentillon]

@pmario That could be solved by not overwriting anything that the plugin does to keep track of it's canonical source, which could even be preferentially used for updates.

[pmario]

From a developers point of view a listed plugin should have some minimum requirements.

• It must follow the plugin naming conventions:
  • $:/plugins/<author or entity>/<plugin-name>/<file names>
• It must have 2 "meta data" tiddlers
  • $:/plugins/<author or entity>/<plugin-name>/license
  • $:/plugins/<author or entity>/<plugin-name>/readme
• It should have:
  • $:/plugins/<author or entity>/<plugin-name>/history .... A short history tiddler, should link to the "long history" in the repository or homepage

I think that's the basics

[pmario]

The "readme" tiddler can already be shown, when you open the library. See:

[AnthonyMuscio]

Yes,

That's why I think it should rise to the top and open automatically and installers can even check requirements encoded in the read me. Wiki text is fully functional there and can even test for dependencies.

In some ways it will only be effective if it is "in your face".

Tony

[pmario]

Wiki text is fully functional there and can even test for dependencies.

Dependencies are defined in the plugin.info file, and are automatically installed if the plugin is installed

[pmario]

see:

[AnthonyMuscio]

Mario

You are talking about the plugin dependencies I am talking about solution dependencies. The designer can choose what appears there in addition to plugin dependencies. It could even warn people like this plugin overrides n core tiddlers for the following reason or just provide a preview or startup documentation.

You could even ask them to acknowledge the licence or detect a previouse version and provide special install info

Tony

[linonetwo]

As a nodejs wiki user, I hope all plugins I installed can be placed into plugins/ folder, so they can be separated from my notes.

This basically means extract some JSON content, and provide a info file if it doesn't have one.

[linonetwo]

As a long-term tiddlywiki user, I hope this plugin library can be free of charge and live long, so I can use it for decades.

Who will need to pay for the server? Microsoft (for npm and github)? Or Google? Or via donation?

[linonetwo]

As a plugin-developer, I hope there can be some template repo to speed up process when I'm writing a new plugin, so I can focus on plugin business logic instead of infrastructure.

What this related to CPL, is that template may standardize the way we write plugins, so CPL can recognize these plugins well.

I'd like to use typescript to develop plugin, and others may just want to create pure css plugin, and some may create wikitext plugin. They need separated templates.