IMPORTANT: All plugins will soon require a wiki page

[Christopher Orr]

Hi all,

Please read this if you're a *Jenkins plugin developer*, as there may be
actions you need to take.

**Background**

As discussed recently on this list and in the community meeting last
week, we would really like to raise the quality bar for Jenkins plugins.
http://meetings.jenkins-ci.org/jenkins/2015/jenkins.2015-05-13-18.07.log.html#l-77

The first step is to ensure that plugins have some documentation.

There are a lot of plugins out there­ — even brand-new ones — which have
no wiki page, and therefore only show minimal information (if any!) in
the Jenkins plugin manager. This makes it hard for users to find out
whether the plugin is suitable, find where the source code is, who the
maintainers are, how to use the plugin, what the recent changes are, for
people to find plugins via Google etc etc..

It was decided that plugins which do not specify a wiki page will soon
*no longer be included* in the Jenkins Update Centre (i.e. the plugin
manager UI within Jenkins itself).
Adding a wiki page for your plugin with an infobox and documentation is
helpful for users, and it is not an unreasonable barrier to entry.

Another problem is that many plugins *do* have a wiki page, but fail to
specify its URL in the plugin metadata (e.g. pom.xml). This makes it
hard for the code that generates the Update Centre to know what the
correct wiki page is.


**What will happen**

* Changes to the Update Centre behaviour (in a few weeks)
There is a pull request which will implement this behaviour, i.e.
ignoring plugins without a valid URL when building the plugin list:
https://github.com/jenkinsci/backend-update-center2/pull/20

This should be merged at some point in June, i.e. in a few weeks.
Exactly when will likely be discussed in the next community meeting.

* Transition period (several months)
Because this change will affect ~10% of all current plugin releases,
there will be a transitional phase, where plugins that don't specify a
wiki page will still be included in the Update Centre.

This happens via the "wiki overrides" mechanism of the Update Centre:
https://github.com/jenkinsci/backend-update-center2/blob/beb31db/src/main/resources/wiki-overrides.properties

Any plugin on that list will remain in the Update Centre until the final
cut-off.

Plugins which have *no* wiki page whatsoever may be temporarily pointed
to a "Plugin Page Missing" wiki page, explaining to users that the
maintainer has not documented their plugin, and that they should be
encouraged to do so. Such plugins will therefore also remain in the
Update Centre during this period.

* Final cut off
After the transitional period, the temporary wiki overrides list will be
cleared out, and any plugins that still do not specify a wiki page will
no longer be listed in the Update Centre.


**Action required by plugin developers:**

1. Check whether your plugin is on either of these two lists:

Plugins which *do not* have a wiki page:
https://gist.github.com/orrc/4c149b62c62362191972

Plugins which have a wiki page, but *do not* list it in the metadata:

https://github.com/jenkinsci/backend-update-center2/blob/beb31db/src/main/resources/wiki-overrides.properties

2. If your plugin is not on either list, there's nothing to do! :)

3. If your plugin is listed here, ensure you have a wiki page:
https://wiki.jenkins-ci.org/x/AgAcAQ#HostingPlugins-CreatingaWikipage

4. Ensure that the correct wiki URL is listed in your plugin metadata:

https://wiki.jenkins-ci.org/x/AgAcAQ#HostingPlugins-AddingyourWikipagetoyourrepo

Examples of how to specify this for various plugin build systems:
Maven:
https://github.com/jenkinsci/git-tag-message-plugin/blob/master/pom.xml#L15
Gradle:
https://github.com/jenkinsci/job-dsl-plugin/blob/31216b7/job-dsl-plugin/build.gradle#L23
Ruby:
https://github.com/jenkinsci/pathignore-plugin/blob/22412e7/pathignore.pluginspec#L7

4a. While you're there, please also make sure that your <scm> info is
present and pointing to your jenkinsci repository, as future Update
Centre changes may enforce this more strictly:

https://wiki.jenkins-ci.org/x/AgAcAQ#HostingPlugins-DeclareyourrepositoryinyourPOM

5. Create a new plugin release (some time before the final cut off)


Please check the above lists, and make the required changes as soon as
possible. Pass on the word if you know any of the maintainers on those
lists.

Feel free also to submit pull requests to the plugins on the wiki
overrides list!

Thanks for reading this far, and let me know if you have any questions :)

Thanks,
Chris

[Bruno Meneguello]

Could be possible to create a "WIKI.md" file in the project's root to automatically create and update the wiki at correct location. Maybe create a maven plugin to check the wiki structure?

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/555D16FA.8040808%40orr.me.uk.
For more options, visit https://groups.google.com/d/optout.

[Michael Willemse]

Hi I'm on the wrong url list (aws-lambda)

The url that I have in my pom.xml is identical to the one in the wiki-overrides.properties file:

<url>https://wiki.jenkins-ci.org/display/JENKINS/AWS+Lambda+Plugin</url>

Is there still something wrong, or is it ok?

Thanks,

Michael

Op donderdag 21 mei 2015 01:21:37 UTC+2 schreef Christopher:

[Christopher Orr]

Hi Michael,

Yes, that looks like a redundant entry in the list — your plugin looks
fine, so you don't need to do anything.
Possibly I had originally added one of the older artifact IDs to the
list (aws-lambda-plugin) or so.

Thanks for checking!
Chris

On 21/05/15 16:32, Michael Willemse wrote:
> Hi I'm on the wrong url list (aws-lambda)
>
> The url that I have in my pom.xml

> <https://github.com/jenkinsci/aws-lambda-plugin/blob/master/pom.xml> is

> identical to the one in the wiki-overrides.properties file

> <https://github.com/jenkinsci/backend-update-center2/blob/beb31db/src/main/resources/wiki-overrides.properties>:

> https://wiki.jenkins-ci.org/x/AgAcAQ#HostingPlugins-CreatingaWikipage <https://wiki.jenkins-ci.org/x/AgAcAQ#HostingPlugins-CreatingaWikipage>

[James Nord]

On Thursday, 21 May 2015 00:21:37 UTC+1, Christopher wrote:

    Plugins which have a wiki page, but *do not* list it in the metadata:
 
https://github.com/jenkinsci/backend-update-center2/blob/beb31db/src/main/resources/wiki-overrides.properties

dockerhub is deprecated and replaced by dockerhub-notification, so that one can be ignored.

[jbull]

Excellent, please remember to keep your wikis up to date if you have time :) 

-- JB 

[Jan Ruzicka]

Hi,

 

Is there any way to incorporate the wiki rule to the release process?

Maven having an additional step that would check wiki page during release and failed when no such thing was present.

Of course there should be an option to override the test (like skip test).

--Jan

--

You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/068ca184-5b79-4aff-845b-847a5ade6c99%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

---

NOTICE TO RECIPIENT: This email, including attachments, may contain information which is confidential, proprietary, attorney-client privileged and/or controlled under U.S. export laws and regulations and may be restricted from disclosure by applicable State and Federal law. Nothing in this email shall create any legal binding agreement between the parties unless expressly stated herein and provided by an authorized representative of Comtech Telecommunications Corp. or its subsidiaries. If you are not the intended recipient of this message, be advised that any dissemination, distribution, or use of the contents of this message is strictly prohibited. If you received this message in error, please notify us immediately by return email and permanently delete all copies of the original email and any attached documentation from any computer or other media.

[Daniel Beck]

On 05.06.2015, at 17:14, Jan Ruzicka <jan.r...@comtechmobile.com> wrote:

> Is there any way to incorporate the wiki rule to the release process?
> Maven having an additional step that would check wiki page during release and failed when no such thing was present.
> Of course there should be an option to override the test (like skip test).

This is something I plan to look into. We initially considered adding a check to Artifactory and reject the upload otherwise, but Artifactory Online does not support user plugins.

[dana...@gmail.com]

There is a maven plugin that checks a pom file to sort that pom. https://github.com/Ekryd/sortpom

Maybe start from there :)

You can easily incorporate it into a build lifecycle

[Jesse Glick]

On Sat, Jun 6, 2015 at 1:41 AM, <dana...@gmail.com> wrote:
> You can easily incorporate it into a build lifecycle

This would be helpful, but only to people who are using a very new
version of the plugin parent POM, thus a very new core dependency.

[Daniel Beck]

On 09.06.2015, at 00:58, Jesse Glick <jgl...@cloudbees.com> wrote:

> This would be helpful, but only to people who are using a very new
> version of the plugin parent POM, thus a very new core dependency.

This may have been a useful first step, but that's how hindsight works.

Still, it's the right thing to do going forward, and maybe it's done in time for the next LTS baseline. Since the archetype tracks that fairly aggressively, it should be in new plugins quickly enough.