Automatic release and update of plugin documentation

[Bue Petersen]

Hi

I have a suggestion or an idea....

I'm tired of the situation where I'm releasing a plugin, and then have to update the plugin wiki page  "just" after. There is always a bit of time-lack where the new plugin release and the wiki isn't matching.

Quite often it is not a big problem, as the plugin wiki page isn't changed much - but stil...

It would have been better to update it as we made decisions during development and so on.

How do you do it?

I would like that we update the plugin wiki page during development (when relevant), but first release it when the plugin is released.

Further I would much rather maintain the wiki page in markdown than in Confluence.

So my idea is to write the plugin wiki page in markdown (or maybe just Confluence mark-up or what-ever), put this/these markdown files in the plugin repository and upon release generate html/Confluence wiki mark-up and publish it.

Confluence have an API for posting pages, but I think it requires some kind of configuration on the server?

Any thoughts on this? Are we the only one that would like this setup? I couldn't find anything on this topic related to plugin development.

Best regards,
Bue Petersen

[Daniel Beck]

What's wrong with keeping an entry called 'Upcoming changes' or '2.4 (unreleased)' up to date? It gives users an opportunity to review and provide feedback on upcoming changes since they're more visible. Then just switch the headline when you release, and you're good.

Putting the files in the repository has at least the problem that stable/bugfix branches (e.g. Subversion Plugin 2.4.x, Git Plugin 2.2.x, Maven Plugin 2.0.x), wouldn't work well with it AFAICT.


Damien Nozay, contributor to Promoted Builds, may be interested in this as well, as he implemented something related for that plugin as well. Discussion (much of which does not apply here though):
https://github.com/jenkinsci/promoted-builds-plugin/pull/54

> --
> 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/CAJB%2BB4VWDzFNszUiVzdrfi1hpe%3D4iC%2B3tvikizmSyv2ZNRFK4Q%40mail.gmail.com.
> For more options, visit https://groups.google.com/d/optout.

[Daniel Spilker]

For the Job DSL Plugin [1] we use the Conflunce wiki page only for a summary and some basic information. For all other documentation we point to the GitHub wiki [2]. The wiki content is kept in the repo [3], so contributors can/must update the docs as part of a pull request. To update the wiki we use the ghpages Gradle plugin [4], which can be configured to update the wiki [5].

So far users seem to find the relevant docs and there have been no complaints. Merging/rebasing the docs has not been more or less painful than merging code.

Daniel

[1] https://wiki.jenkins-ci.org/display/JENKINS/Job+DSL+Plugin
[2] https://github.com/jenkinsci/job-dsl-plugin/wiki
[3] https://github.com/jenkinsci/job-dsl-plugin/tree/master/docs
[4] https://github.com/ajoberstar/gradle-git/wiki/org.ajoberstar.github-pages
[5] https://github.com/jenkinsci/job-dsl-plugin/blob/master/build.gradle#L139

[Bue Petersen]

Hi Daniel and Daniel

Thanks for the feedback, refs and thoughts - I very much appreciated it. So I just want to post my feed back here (possible for others to read as well)...

Daniel Beck wrote:
> What's wrong with keeping an entry called 'Upcoming changes' or '2.4 (unreleased)' up to date? It gives users an opportunity to review and provide feedback on upcoming changes since they're more visible. Then just switch the headline when you release, and you're good

The problem I see is that I can't directly relate the documentation change to a code change. I want that for traceability, and to easier ensure that if code changes should change users or devs docs, it becomes visible if there isn't any changes in the docs.

Daniel Beck wrote:
> Damien Nozay, contributor to Promoted Builds, may be interested in this as well, as he implemented something related for that plugin as well. Discussion (much of which does not apply here though):
https://github.com/jenkinsci/promoted-builds-plugin/pull/54

There are some great discussion points, both in favour and against having docs inside the repo. In our case we have very structured process, so the issues about pull requests with release notes won't be a big problem for us.

We won't duplicate documentation though, but instead I think like Daniel Spilker suggest that we have some pretty stable content on the wiki that help users get going with basic and recommended setups. The details and all other things are put in the repository. That way only major changes need to update the wiki.

I'm pretty much along those lines you suggest. My small experiments showed that it would probably be the best solution to have rather static content on the plugin wiki page, and then keep what changes more often (especially when code is changes) in the repository.

I haven't figured out an easy way to autogenerate a plugin wiki page (from repository documentation content) and post it automatically upon release. That would have been the perfect solution ;-)

Thanks for your answers.

Best regards,
Bue Petersen

--

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/c97c4487-0e94-4ef2-bca9-2ee0c05456ee%40googlegroups.com.