Extend create plugin docs

[qwerty287]

closes #1389
closes #1033

[woodpecker-bot]

Deployment of preview was successful: https://woodpecker-ci-woodpecker-pr-3062.surge.sh

[lafriks]

It would also be nice to add a go plugin sample and it's dockerfile

[qwerty287]

Would it also be enough to just link to a simple example? (E.g. the extend env plugin)

[pat-s]

We should really find a central place for plugin documentation (both for dev and users). I still find it unfortunate that plugins are split between CB and GH.

Btw there is also https://codeberg.org/woodpecker-plugins/go-plugin.

[qwerty287]

We should really find a central place for plugin documentation (both for dev and users). I still find it unfortunate that plugins are split between CB and GH.

But docs are completely here, right? If you mean that docs for go-plugin are at CB: Yes, that's correct but I think it's better to keep it in the same repo (yes, the plugins split in general should be solved, but that's another issue).

Btw there is also https://codeberg.org/woodpecker-plugins/go-plugin.

Yes I mentioned it.

[pat-s]

But docs are completely here, right?

I guess this would be the best.

We have a recent use case which also exactly tackles this topic: https://codeberg.org/woodpecker-plugins/node-pm/issues/21

Any effort on improving the situation is great 👍

[qwerty287]

We have a recent use case which also exactly tackles this topic: https://codeberg.org/woodpecker-plugins/node-pm/issues/21

Yes, but this is plugin specific and should be in the individual plugin's repos.

[pat-s]

Two additional points worth mentioning:

• Plugins on CB are also published to the CB package registry
• renovate should be used to keep dependencies up-to-date
• Encourage the use of https://github.com/woodpecker-ci/plugin-ready-release-go (?)

[qwerty287]

Plugins on CB are also published to the CB package registry

This should be added to the individual plugin docs.

renovate should be used to keep dependencies up-to-date

I don't think that's really a "best practice". Of course your deps should always be up-to-date, but you can do that manually or using github's dependabot or whatever else too.
Adding just a best practice that says "keep your dependencies up-to-date": I don't want to write best practices for programming in general. Instead, these should be specific for woodpecker plugins.

Encourage the use of https://github.com/woodpecker-ci/plugin-ready-release-go (?)

The same applies here too, with some issues:

• no gitea/gitlab/bitbucket support (yet)
• it probably does not match every use case
• using plugins like this to simplify your release process is also a general point and nothing plugin-specific

[6543]

i agree the docs should not be for our official plugins but rather for everybody who want to make there own.
and the programming practices might vary

[pat-s]

Programming practices is one thing but if there are no general "rules" how to format/maintain/publish/release plugins, everybody will do something else and in the end it's just a mess for users (and devs).
That's what linters are for, that's what other implicit "contributing" rules are for.

At least in repos which live within the GH and CB woodpecker org we should have such rules. In a central place. How devs then comply with these rules is a different thing. I am actually aiming to draft something for a long time already (content TBD) but I don't think being "too open" or "too lax" is really helping in the long-term. Yes, it's FOSS, yes individual contributors with (many) own opinions, but if this project wants to grow in a smooth way, there is no way around such rules in the mid and long-term.

This should be added to the individual plugin docs.

I disagree. This is a perfect point showcasing what I wanted to say above: sure, it doesn't hurt anyone if a plugin is published there or if not. But if there is no rule, the ratio of plugins available there will be maybe like 70/30 (available/not available) and users have to look up every time the specific state for this plugin. This is already the case with the availability of plugins in CB or GH. There was no rule, nobody knows why the current state is like it is and users are also partly confused.
This is just one example, the same applies for

• semver
• conventional commits
• updates
• naming
• README content
• etc.

I hope you understand what I want to say 😄 I don't want to make things too complicated and surely enjoyable for everyone. And many things are great. But there are (quite some) points where everyone is just 🤷🤷🤷 and in the end this will cause issues/lot of unnecessary typing/unprofessional look of the project.

i agree the docs should not be for our official plugins but rather for everybody who want to make there own.

And I also disagree with this with the arguments from above.

No hard feelings, just opinions ❤️

[qwerty287]

I disagree. This is a perfect point showcasing what I wanted to say above: sure, it doesn't hurt anyone if a plugin is published there or if not. But if there is no rule, the ratio of plugins available there will be maybe like 70/30 (available/not available) and users have to look up every time the specific state for this plugin. This is already the case with the availability of plugins in CB or GH.

I don't think so. You have to look up the plugin docs anyways to check the settings, and there you can also find the image locations.

At least in repos which live within the GH and CB woodpecker org we should have such rules.

Yes, I get your point and I also think that such rules are good for our org. However, let me ask another question first: Should the woodpecker org be a "home" for plugins created and maintained by anyone or just maintained by woodpecker maintainers? (I think the later is the better option.)

Anyways, this discussion is kinda off-topic for this PR and requires some more discussion first. Can we move it to its own discussion and go on here? We can add rules or more best practices etc. later too.

[6543]

@pat-s @qwerty287 as a owner I think this pull is ready.

And so I'm going it merge it now :)

for the guidelines, I open a new discussion

[6543]

• Guidelines for plugins #3085