Re: improvements to the Developers Reference maintenance workflows?
On 03/07/14 at 11:27 +0200, Lucas Nussbaum wrote:
> 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?
Hi,
An update on this:
I moved developers-reference to collab-maint and Git, and uploaded a new
version (mainly to reflect this change in Vcs-*). I've also filed a bug
(#754189) to remember to document the expected maintenance workflow.
Next steps are:
- review current patches in the BTS
- send a call-for-help to d-d-a
- recruit co-maintainers, and maybe consider stepping down as maintainer
ourselves (something I'm definitely doing :-) )
- review current bugs in the BTS
(to be clear: these are open for takers, though I might try to do some
of it myself if nobody else does)
Lucas
Reply to: