Re: improvements to the Developers Reference maintenance workflows?
Hi,
I wonder if the problem is format or content provider.
On Thu, Jun 19, 2014 at 09:05:17AM +0200, Raphael Hertzog wrote:
> (adding debian-doc to the cc)
> Hi,
> On Thu, 19 Jun 2014, Paul Wise wrote:
> > Some of you may be aware there has been a discussion about devref on
> > debian-private and debian-project, the threads started here:
> >
> > <20140613131135.GA7215@x61s.reliablesolutions.de>
> > https://lists.debian.org/20140618120859.GA7048@jwilk.net
>
> Yes, I saw it and wanted to chime in... but I did not find the time
> and motivation and wanted to see where the discussion would lead.
>
> > Switch to a different documentation format that more people are able to
> > write, this probably too much work to be useful though.
>
> I don't think this is the real blocker. People should be free to submit
> content without markup (or with wiki-like markup), it's easy to integrate
> the content and add the small bits of docbook markup.
True. (Only question is who has time and motivation to do this.)
If you are serious about exporting to DocBook XML, you may need to
assess which wiki platform to use and write some XSLT scripts etc.
(ikiwiki + git + XML converter ... seems good choice over moinmoin)
> > Switch from svn to git. Many people prefer git to svn, this might
> > increase the amount of people willing to contribute.
> I would definitely welcome this, I'm using git-svn anyway currently.
>
> The debian-doc group uses svn for historic reasons but I don't think
> that anyone would oppose switching the devel-ref (which has always been
> treated in a special way). I don't know if the debian-doc alioth project
> granted commit rights to debian developers by default. But, if not, we
> should certainly do it.
Many active DDP documents are in git repo these days. You can set it up
in ddp directory, if you wish.
> > Publish directly to the website on each git push. This would make the
> > devref copy on the website less stale. An alternative might be weekly or
> > monthly releases to the archive.
>
> We used to do this but:
Yes.
> 1/ the www team wanted to get rid of this because maintaining a proper
> build environment was causing regular problems (eg due to version skew
> between stable (the www build environment) and unstable (the package build
> environment)).
>
> 2/ the supplementary delay was seen by some people as a good thing so that
> changes can be better reviewed before being pushed to the wide public
>
> 3/ some believe that the content of the package is as important as the content of the
> website and we should release more often to avoid those delays
4/ Translation is in sync using PO4a (which seems to be lacking in wiki
available as wiki.debian.org, yet.)
> So yes, we should do monthly releases (weekly is a bit too much IMO).
>
> > Add an ACL so that all Debian members are able to commit (or move to
> > collab-maint). This would lower the bar for contributions, allow trivial
> > issues to be fixed easily and reduce change latency.
>
> I have no problem with this but others have had with this way of working.
>
> With Andreas Barth, while we were disagreeing about the way to maintain
> this package, we agreed that direct commit was not really acceptable and
> that each patch should be sent to the BTS for review. Explicit ACK or
> lack of opposition could then be used to commit the changes.
The work flow of wiki and this kind of resolution does not go well.
> Steve Langasek was also strongly in favor of some prior review because the
> document ought to define the best practices for the project and changes
> without buy in from the project at large would be detrimental.
Quite understandable.
> > Call for help so that more people get involved and more issues get
> > fixed. This could be a single mail to d-d-a or a DevNews entry. This
> > should probably only happen after some improvements are made.
>
> Yes.
Wait a moment, what we need is not to work on format conversion or new
system but the contents used for the dev-ref.
More practical thing is people to set up proposal pager organized to
match dev-ref chapters with alternative and additional contents. (This
could have been done but I did not see such activity to supplement
dev-ref except for some multi-arch transition and compiler flag
updates.)
Then file bug requests to maintainers. This can be done now without any
new system.
As long as it is well known place, people can always reference it as
secondary resource. Wiki comes with ease of access but also comes with
many stale outdated pages as you know. So the review and integration as
we see now is very valuable thing.
If a wiki chapter get big enough, we can add it to a new chapter.
If update of the dev-ref stalls and wiki pages grow big enough, making static
XML from it can be our task, then.
With the resource we see, I am a bit skeptical on spending resource to
new things like setting up wiki based platform while breaking somewhat
working iwork flow. Of course, someone volunteer and execute this task,
I am happy him doing it.
Regards,
Osamu
Reply to: