* Plugin Author Guidelines in KB

[Mark1834]

There have been various discussions here over the past couple of years on what plugins should and should not do, as there are no specific requirements or review criteria published either here or in the Plugin Store.

I have been working with ColeValleyGirl to remedy that omission, and the output from that is now available here on the Knowledge Base.

These new requirements and recommendations are designed to provide a basic framework for authors, and to help answer the two most common questions from new plugin users, namely, “How do I know this plugin is safe?”, and “How do I recover from making a mistake using it?”.

Over to both authors and users for comments…

[ColeValleyGirl]

I'm planning to add a user tutorial on Choosing and Using Plugins to the KB (it's written; I'm just contemplating whether to include a video with it...)

[tatewise]

That is a good framework.

How is Mandatory Requirement 2. interpreted in the context of restoring a backup of user settings?

Is Mandatory Requirement 5. referring to uploading data to cloud storage? Perhaps that should be made clearer.
Is there any other way data could be uploaded?

There are several references to just 'Store' which I think should say 'Plugin Store'.

Is this article a good place to describe plugin lifecycle processes such as:

• How to link plugins to FHUG for one-off temporary use and beta-test versions.
• How and when to disable those links.
• How to add/update plugins via the Plugin Store (some of the Draft/Review options are not very clear).
• How to advise users where questions requesting help should be posted.
• How to add/update additional help pages (some of the Draft/Publish options are not very clear).
• How to delete plugins for the Plugin Store (which is not intuitively obvious).

[Mark1834]

"How is Mandatory Requirement 2. interpreted in the context of restoring a backup of user settings?"

I think that one is straightforward - when restoring a backup using one of the plugins, the plugin should warn explicitly that current settings will be overwritten and lost. Perhaps neither one is compliant at the moment, but we can fix that in future revisions.

"Is Mandatory Requirement 5. referring to uploading data to cloud storage? Perhaps that should be made clearer."

If it is revised to "Plugins must not upload any user data (including anonymous usage statistics) under any circumstances" that is probably more explicit. My instinct is that plugins should only write to local files, and it is up to the user to manage cloud storage and syncing.

I would rather not confuse what should be done with how it is done, but the bullet points would be a good basis for a complementary article for authors on plugin mechanics.

[ADC65]

I only really write plugins for my own use, but I have shared some on the forum previously. As such, my feedback is based on being a user rather than an author.

My first observation is in Mandatory Requirement 4. It seems incorrect to 'strongly discourage' something that is labelled as a 'mandatory requirement'. It is either mandatory or it is not. If it is mandatory, it should not be allowed, or if it is not mandatory, it should not be mentioned as a restriction.

Secondly, and more importantly in my opionion, is in Mandatory Requirement 5. A number of popular plugins check to see if there is a later version of the plugin available, and in some plugins this feature is not optional. i.e., it will perform the check whether the user wants it to or not. To do this, it has to upload data about my current version number, which in my opinion is user data. Hence plugins that currently do this will need to stop doing it (a good thing in my opinion, although I know others disagree). Note that the wording of the requirement ("under any circumstances") means that even giving the user the option is not allowed.

[Mark1834]

I would be happy with "is not permitted for either Plugin Store plugins or plugins linked from FHUG", but what does FHUG admin think?

Maybe it's a pedantic point, but if the version checker downloads the version number of the store plugin and compares it with local data on the current version, I think it's compliant. It's only Mike that has implemented silent version checks, but the same may apply for Jane's plugin that checks all installed plugins against the store. Comments from those authors welcome...

[ADC65]

I did mean to add that it's a good framework and thanks to you both for putting the time into it.

I believe Ancestral Sources also does version checks that can't be switched off, but my point was general and I didn't want to start picking out people or plugins for criticism. The rules will apply to plugins written in the future as well, so I thought I'd just point out a consequence of the wording. You're probably right that it's technically downloading something rather than uploading, so it may not be an issue anyway. (I have to add it doesn't affect me as I hack the code to stop it checking anyway.)

[Mark1834]

Indeed - we are in no way aiming at any existing plugins, but pointing out specific examples is useful for illustrating general points. I've already updated one of my Store plugins that did not ask for confirmation when updating a settings file!

[tatewise]

Yes, the Check Version in Store process only uploads the name of a plugin to retrieve the version in the Plugin Store, which is compared with the version installed in FH.

My Lookup Missing Census/BMD plugins produce URL in a browser table that when the user clicks on them uploads the URL details such as names, dates & places to search Ancestry, FMP, etc. So presumably the user clicking on those URL is not integral with the plugin.

[ColeValleyGirl]

I would be happy with "is not permitted for either Plugin Store plugins or plugins linked from FHUG", but what does FHUG admin think?

It's a fair point, and on reflection I think it ought to be mandatory for plugins linked from FHUG as well, (although as you say later they aren't checked in any way).

[ColeValleyGirl]

My Lookup Missing Census/BMD plugins produce URL in a browser table that when the user clicks on them uploads the URL details such as names, dates & places to search Ancestry, FMP, etc. So presumably the user clicking on those URL is not integral with the plugin.

If a plugin displays results with a visible link that the user can click on to open or not, and opening that link is subject to the normal security checks in that user's browser (whatever that might be/however they've configured it) I think that's fine.

[NickWalker]

I believe Ancestral Sources also does version checks that can't be switched off, but my point was general and I didn't want to start picking out people or plugins for criticism.

Ancestral Sources isn't a plugin

[tatewise]

Regarding Mandatory Requirement 4. using libraries, I don't see how it would be possible for a linked FHUG plugin to invoke separate libraries, which would not exist in the user's file system unless they were downloaded separately via another link.

My 'Map Life Facts' plugin uploads/sends Place &/or Address details to various geocoders (Google Maps, etc) but only after the user has obtained an access key to the geocoder service, so does that constitute user approval?
Nevertheless, it violates Mandatory Requirement 5, which does not allow for user approval.

[ColeValleyGirl]

Regarding Mandatory Requirement 4. using libraries, I don't see how it would be possible for a linked FHUG plugin to invoke separate libraries, which would not exist in the user's file system unless they were downloaded separately via another link.

Doesn't need a link. Just copy the loadrequire snippet and modify it to use another ftp location. Many of us have the capability to host libraries downloadable via ftp... This is definitely not acceptable.

My 'Map Life Facts' plugin uploads/sends Place &/or Address details to various geocoders (Google Maps, etc) but only after the user has obtained an access key to the geocoder service, so does that constitute user approval?
Nevertheless, it violates Mandatory Requirement 5. So does this need a user approval condition?

If the documentation is clear about what is uploaded and why, and the user has to take known and visible steps to allow/enable it, seems OK to me.

Same if (for example) a plugin displays online help in a browser. Should be find as long as the documentation is clear that this is what will happen. I do have a V6 plugin that downloads a help (.chm file); the documentation says it will do this -- should the plugin ask for permission (and exit if it doesn't get it -- I'm not supporting a complex plugin if the user has declined to use the available help)?

My concern is hidden downloads or uploads.

[ChrisRead]

Is this article a good place to describe plugin lifecycle processes such as:

• How to link plugins to FHUG for one-off temporary use and beta-test versions.
• How and when to disable those links.
• How to add/update plugins via the Plugin Store (some of the Draft/Review options are not very clear).
• How to advise users where questions requesting help should be posted.
• How to add/update additional help pages (some of the Draft/Publish options are not very clear).
• How to delete plugins for the Plugin Store (which is not intuitively obvious).

Having literally gone through this for the first time over the last fortnight, I have to agree with the points raised by tatewise.
Points 1&2, I'm sure I've seen mentioned somewhere about using one of the sharing services. I happened to use OneDrive as I have it and it's simple to provide a share. We could use some consistent 'rules' about how long to share for and how to notify of updates etc. during what might be called beta testing (although direct interaction with those testing would probably be the best way rather than spotting a post in the forum), and then when to remove the share as it transitions to published.
Point 3, I read the plugin publish FAQ and followed it, but the using the authors page is rather hit and miss and somewhat unclear, with unexpected consequences. I haven't seen any guide about what affect doing something on it does, so it was a bit trial and error. For example, I was surprised when my plugin disappeared simply because I re-aligned an image on the plugin page text, and had to go round the publish route again.
Point 5, when you create a Help page, you can't link it to the plugin until it is published as it is not in the list, although it does seem to remember if you don't actually need to change the Help. So, again some information on using the author help page similarly to the plugin page.

I now need to go read the Guidlines and see if I need to write another essay.

[Mark1834]

Is there an analogy between the Map Life Facts plugin and internet data matches in the main FH application?

FH includes links to the privacy policies of both FMP and MyHeritage (which are headquartered in the UK and Israel, respectively). If a plugin is uploading user data to a third party mapping service, should it also include a link to that service's privacy policy when it requests permission?

[tatewise]

My 'Map Life Facts' plugin uploads/sends Place &/or Address details to various geocoders (Google Maps, etc) but only after the user has obtained an access key to the geocoder service, so does that constitute user approval?
Nevertheless, it violates Mandatory Requirement 5. So does this need a user approval condition?

If the documentation is clear about what is uploaded and why, and the user has to take known and visible steps to allow/enable it, seems OK to me.

Same if (for example) a plugin displays online help in a browser. Should be find as long as the documentation is clear that this is what will happen. I do have a V6 plugin that downloads a help (.chm file); the documentation says it will do this -- should the plugin ask for permission (and exit if it doesn't get it -- I'm not supporting a complex plugin if the user has declined to use the available help)?

My concern is hidden downloads or uploads.

However, Mandatory Requirement 5. has no escape clause and does not mention hidden downloads:

5. Plugins must not upload any user data under any circumstances.

Regardless of the documentation or user permission, the examples above violate Mandatory Requirement 5.
So should I delete Map Life Facts from the Plugin Store to avoid breaking the mandatory rules?
It has an analogy with the FH Map Window geolocation features and does not mention privacy of any of the services it uses.

[Mark1834]

That's why comments were invited - to fine tune the document and find these wrinkles. So far, it's going well. Nobody is pushing back against the principle of what we are doing, so I'll see what emerges over the next 24 hours and capture the essential points in a revised version tomorrow.

These guidelines need to be general, not directed at any particular plugin, but I think we have to be a little more careful where the user is uploading their data to a commercial third party. If I can find a short phrase that includes that but without making the document too legalistic, I'll include it in the revision.

[ChrisRead]

OK, incoming essay as promised
Mandatory Requirements
General, as they are mandatory, use the term MUST or equivalent, no use of SHOULD or similar.
Point 1: Should state what those specific FH keys are for clarity and removal of doubt.
Point 2: Seems reasonable.
Point 3: Unclear what 'more than one step' actually means in practice, as that all depends on the interpretation and granularity of operations. The given example could do with 'dumbing down' in line with Point 2 'non-technical user' even if technical users are probably who it's aimed at.
Point 4: The first sentence is irrelevant, as the second one should be reworded to state exactly how the plugin should be implemented/packaged. The use of 'discouraged' is again irrelevant to a mandatory requirement, and harks back to the first sentence again. State what is mandatory, and don't muddy the waters. The 'irrelevant' bits may of use as separate information for developers, somewhere else.
Point 5: Seems very reasonable.

Style, Scope...
Point 1: The versions supported are part of the author page. Are there any options to add other restrictions as mentioned to the page, or are there too many, or no ability to have the author page revised. If so, then maybe there should be a 'standard' disclaimer that a plugin puts in its plugin information page at the top.
Point 2: Seems reasonable, but who is reviewing the UI & Help, and what will be the feedback process. See Review Process comments.
Point 3: This in some way harks back to the mandatory point 2 regarding how to 'talk' to the intended audience. I have noticed a dearth of help for many plugins, which I can sympathise with as an ex-softie, but I've always tried to provide useful help with an application. I assume sometimes people think, it's simple, can't you figure it out for yourself. Doing help is an unfun part of developing software.
Point 4: Seems reasonable, however, it would be nice to have a 'style' FAQ that can be referred to by novice developers in particular. I was very unsure of the best way to organise the code, as the LUA documentation wasn't particularly helpful in that aspect. Hence, I feel I have ended up with a plugin that 'evolved' in style as I learnt due to not having any written guide. As a result it could do with a damn good polishing.
Point 5: I think this is restating some of the mandatory points regarding user data changes, as it is something that should be clearly stated in the description anyway regardless of being draft or final version, and so is a redundant recommendation if more firmly included in the mandatory section.

Review Protocols
I was surprised how easy it was to get the plugin published, I'd expected some sort of push-back maybe. The screening process and check points really should be clearly documented to avoid any doubt by developers. These should also relate back to the mandatory points for clarity, and why a plugin has been declined to be published. If there are review points that would cause rejection, they should be included as mandatory requirements. This is basically about what the steps of the publish and review are, and what is expected of the reviewers (and how to apply the rules) and the developers (how to respond to feedback).

Overall, having just gone through the whole process as a novice plugin developer, but with 40+ years of software development experience, it is clear that this has been working reasonably successfully by good will. However, it will not be a waste of effort to at least lay some clearer ground rules without frightening off potential new (or lurking) plugin developers.

[Mark1834]

Is context the key here? If we were creating processes for a blue-chip company that had to pass review by pedantic attorneys, I’d probably agree with much of that (been there, done that, got the scars to prove it ).

However, CP are a company with two employees and a single product used almost entirely by hobbyists. Who exactly is going to do all this good stuff, and what don’t they do while they’re doing it…?

[ChrisRead]

Is context the key here? If we were creating processes for a blue-chip company that had to pass review by pedantic attorneys, I’d probably agree with much of that (been there, done that, got the scars to prove it ).

However, CP are a company with two employees and a single product used almost entirely by hobbyists. Who exactly is going to do all this good stuff, and what don’t they do while they’re doing it…?

I somewhat agree with this sentiment, but it does not harm to provide some clear guidance to plugin developers. There are a few dos and don'ts encompassed in what has been written that are useful for the inexperienced (and probably the experienced). My comments are based on the need to be unambiguous and clear if you are trying to do something like this. As it is, there aren't really many rules, and it's more of an exercise in codifying things known or obvious to a few.

[ADC65]

Ancestral Sources isn't a plugin

Of course My error, sorry. Because I use the plugin to access it, I was making that mistake. Apologies.

[ColeValleyGirl]

Point 1: Should state what those specific FH keys are for clarity and removal of doubt.

Already documented elsewhere in the KB, and shouldn't be duplicated.

Point 4: The first sentence is irrelevant, as the second one should be reworded to state exactly how the plugin should be implemented/packaged.

We're explicitly recognising that plugins written for personal use and never shared can be much more optimally structured, but that this isn't supported for plugins published for general use (for security reasons). So the first sentence is relevant in identifying what isn't allowed. Rewording might make things clearer...

Many of the more general points you make will be helpful to anyone embarking on a 'How to write plugins: a personal view' article (not me) or updating Getting Started Writing Plugins.

Review Protocols
I was surprised how easy it was to get the plugin published, I'd expected some sort of push-back maybe. The screening process and check points really should be clearly documented to avoid any doubt by developers. These should also relate back to the mandatory points for clarity, and why a plugin has been declined to be published. If there are review points that would cause rejection, they should be included as mandatory requirements. This is basically about what the steps of the publish and review are, and what is expected of the reviewers (and how to apply the rules) and the developers (how to respond to feedback).

This should be aimed at Calico Pie, I suggest, because you're asking to make changes to https://pluginstore.family-historian.co ... ugin-store.

[ColeValleyGirl]

Point 1: Should state what those specific FH keys are for clarity and removal of doubt.

Already documented elsewhere in the KB, and shouldn't be duplicated.

Plus, I strongly suspect the only circumstances in which modifying any registry keys would be allowed is when restoring settings.

Can anyone think of a use case other than that?

[ChrisRead]

Already documented elsewhere in the KB, and shouldn't be duplicated.

In which case, it's simply a case of providing a link to the information in the requirement.

Also, I'm not sure of when registry keys would want to be altered except for restoration.