Guidelines for plugins

[6543]

Based on the idea of #3062 (comment)

why not define some baseline criteria who plugins have to meet before we let them be added. this way we ensure the listed plugins have a certant quality.

like they must follow semantic-versioning or have a mechanism to automatically get notified or better also automatically get there dependency updated ...

[pat-s]

Thanks for this discussion.

I think guidelines will help both users and devs. I'll propose some points as a starting point for a discussion. Of course, these rules can only be enforced in forge orgs of the orgs, not outside. Putting a plugin into an org should come with some benefits. For example, I would suggest to only list plugins in the official overview if they live within the org and comply to these rules. Of course anyone can create any plugin (which is great) but the more plugins exists which follow the same rules, the easier it will be for users.

• Versioning: Use semver (discussion: with or without v prefix? We're not consistent here right now and I think it would help everyone if we would)
• Maintainers: Add a section to the README who maintains this plugin and should be tagged for PRs (this means we need to find official maintainers for every plugin but this will help everyone in the end I guess)
• Dependencies: Keep dependencies up-to-date. renovate is an option/offer, not a must. But it's easy to set up and if not used, we should define time-based rules how often dep updates should happen
• Linters: add linters (list: tdb). Precommit also helps but is optional.
• PRs: add workflow to build PR images for simplified testing
• Release helper: optional but encouraged. https://github.com/woodpecker-ci/plugin-ready-release-go - also soon available for Gitea
• Forge choice: add an information that plugins can either be added to CB or GH (whatever forge maintainers prefer). Maybe we should even open a dedicated woodpecker-plugins org on GH to have similar names and a dedicated place for plugins?

Let's discuss. I can edit/maintain the points above so we have a curated list and an overview of the discussion.

@woodpecker-ci/maintainers

[pat-s]

Yes, long discussion. Usually, such discussions are tackled in personal meetings/calls. But here it's different, of course :)
Some clarifications, as I think my positions haven't' yet fully been understood:

So you would only create guidelines for plugins developed by us? (If we don't allow externally developed plugins.)

They should apply to all but as we all know, we can only control/enforce them among our orgs. But if we encourage the development of external plugins, there should be a way to distinguish "official" plugins (which would imply following the developed rules) from others.

Well, then we don't have to add it to our org. The dev can just leave it under their own user account.

There are big differences WRT to where the plugin lives. In our org we have the "control" (i.e. we can archive it if necessary, apply changes). In external repos, we don't.

If we only allow plugins that follow specific rules, we would have to check if they still follow these rules and we don't have the resources for this

Yes, but we also don't want to have a "wild west" and just let everybody do whatever. This helps nobody. And by ensuring central workflows, linters, etc. a big chunk of this can be automated.

I don't think it's a good idea to let users create plugins and then just add them to the org because the users don't want to maintain it and we should do this. Of course, if we use the plugin in our own repos, we can do this, but otherwise I wouldn't allow this.

Of course, that's a potential issue. That's why I requested explicit maintainers and not just "the maintainers team". As with the latter, nobody will do it as it's "only" a group. By having explicit maintainers, people can be "judged" and actions can be taken by admins if nothing happens. E.g. if an external person moves it to the org and then doesn't maintain it, we can archive it.

---

Overall, I see the biggest discrepancy in our view on the ability to enforce general rules on all repos and "trust" individual people to do their job WRT maintenance. As a user I would prefer seeing one or two dedicated people listed as being the responsible people to tag for an issue/PR instead of a large group and then "hope for the best".

I've contributed many years to a similar large project which was split up into many small repos (similar to the plugin style here) and we had "great" success in moving away from "somebody of the group will surely eventually do it/reply" to assigning maintenance explicitly to individual users who make sure to enforce shared guidelines and reply to issues/PRs. (Happy to share more in private if of interest).

[qwerty287]

Usually, such discussions are tackled in personal meetings/calls

Maybe it's time for #2146 :)

As a user I would prefer seeing one or two dedicated people listed as being the responsible people to tag for an issue/PR instead of a large group and then "hope for the best".

Sure, that's a good idea, but it's easy to do this by just adding a comment to the readme. However, plugins having this should not be marked as "developed by Woodpecker Authors" anymore I think.

I think one of my issues is that I would like to separate official plugins - a different "official" than what you wrote, because I think "official" means developed by Woodpecker Authors - from 3rd-party plugins.

Maybe, your approach in having a central org with guidelines is a good idea, but then I'd like to suggest to have really official plugins in another org (e.g. the woodpecker main org). Of course, these should also follow any guidelines we introduce.
I'd say the plugins that are really developed by woodpecker authors and not just single persons of them are plugin-git, plugin-docker-buildx, and plugin-ready-release-go. Also, I'd add plugin-github-release, plugin-surge-preview, plugin-prettier and plugin-codecov to this list as they're also developed by multiple persons of us and they're pretty essential for our own workflows.

[zc-devs]

If I'm concerned, I'm with @qwerty287 mostly.

Make the rules, follow them, show best practices (let's call it).

However, I don't see the point to move third party plugins to the org. The current list of plugins is enough to me. If I, as a third party plugin developer, want some respect/promotion in the list, then I can apply for the trusted label. In this case I should implement some rules, of course.

[pat-s]

I think I am still misunderstood. I didn't mean to say that plugins must be moved to the plugins org. We should allow people to move plugins there and maintain them (for centralization reasons) which would of course then come with the "burden" to apply to our "rules".
The rule suggestions from above would, of course, only apply to the plugins within the org as we can only enforce them there.

If we add plugins to the plugins list, there must be a clear way to identify plugins which follow our rules/a certain standard compared to "indy" ones. Otherwise, users and the project itself suffers from potentially outdated or badly developed ones.

(@zc-devs Not sure if I was really misunderstood but the part of your reply which says "However, I don't see the point to move third party plugins to the org" gives me the feeling that you understood it as me proposing "plugins must be moved to the org")

[zc-devs]

allow ... burden

I got it. Don't want to repeat qwerty. That burden lean on maintainers also.

for centralization reasons

There should be some "marketplace" of plugins, of course. To me, current list seems centralized and works as marketplace.

identify plugins which follow our rules

Labels already there.

potentially outdated or badly developed

Life is life. This is subjective. Everybody have own head.
In case of trusted plugins, maintainers just need to remove the label and not to deal with removing repository, taking down access, etc.