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