Automatic release and update of plugin documentation

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

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


--
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 [hidden email].
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.
Reply | Threaded
Open this post in threaded view
|

Re: Automatic release and update of plugin documentation

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

On 15.12.2014, at 08:33, Bue Petersen <[hidden email]> wrote:

> 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
>
>
>
> --
> 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 [hidden email].
> 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.

--
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 [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CB57535B-07AF-417F-AEAE-01A99B25C34D%40beckweb.net.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Automatic release and update of plugin documentation

Daniel Spilker
In reply to this post by Bue Petersen
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

--
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 [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/c97c4487-0e94-4ef2-bca9-2ee0c05456ee%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Automatic release and update of plugin documentation

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.

Daniel Spilker wrote:

> 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

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



On Mon, Dec 15, 2014 at 12:36 PM, Daniel Spilker <[hidden email]> wrote:
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

--
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 [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/c97c4487-0e94-4ef2-bca9-2ee0c05456ee%40googlegroups.com.

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

--
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 [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAJB%2BB4WcrD%2BnowkEnNQ4ZkEtvz_FJC7U%3D9pKTHQLW28g4%2Bb7aA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.