Re: improvements to the Developers Reference maintenance workflows?
TL;DR: skip to last paragraph
Hi,
Paul, thanks a lot for summarizing the discussion.
On 19/06/14 at 09:05 +0200, Raphael Hertzog wrote:
> > 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.
I agree that docbook might not be the most user-friendly format, but I
also find it difficult to believe that it is a blocker.
Its two main features are:
- it is a format that is easily converted to lots of other formats
- it's easy to translate
I have no strong opinion against moving to another format with the same
features, but don't plan to invest time myself on this.
> > 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.
I would be fine with moving to Git. We could also move dev-ref out of
debian-doc (to collab-maint?).
> > 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.
I think that the policy should be:
- consensual changes can be committed by anyone
- non-consensual changes should be discussed on the BTS prior to being
committed
When someone commits something thinking it is consensual, but the change
ends up being non-consensual, it can simply be reverted.
> > 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.
An easy improvement is to switch to Git and collab-maint, and to
announce that direct commits of consensual changes are OK.
After that, we could call for help.
Raphael, Marc, are you fine with that?
Lucas
Reply to: