Re: improvements to the Developers Reference maintenance workflows?

[Raphael Hertzog <hertzog@debian.org>]

(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.

> 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.

> 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:

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

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.

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.

> 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.

Cheers,
-- 
Raphaël Hertzog ◈ Debian Developer

Discover the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/