Re: improvements to the Developers Reference maintenance workflows?

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: improvements to the Developers Reference maintenance workflows?

Raphael Hertzog-3
(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:
>
> <[hidden email]>
> https://lists.debian.org/20140618120859.GA7048@...

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/


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: https://lists.debian.org/20140619070517.GA21679@...

Reply | Threaded
Open this post in threaded view
|

Re: improvements to the Developers Reference maintenance workflows?

Osamu Aoki-5
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:
> >
> > <[hidden email]>
> > https://lists.debian.org/20140618120859.GA7048@...
>
> 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


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: https://lists.debian.org/20140620120051.GA29694@goofy

Reply | Threaded
Open this post in threaded view
|

Re: improvements to the Developers Reference maintenance workflows?

Lucas Nussbaum-4
In reply to this post by Raphael Hertzog-3
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


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: https://lists.debian.org/20140703092759.GA26317@...

Reply | Threaded
Open this post in threaded view
|

Re: improvements to the Developers Reference maintenance workflows?

Raphael Hertzog-3
Hi,

On Thu, 03 Jul 2014, Lucas Nussbaum wrote:
> 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?

Yes.

Cheers,
--
Raphaël Hertzog ◈ Debian Developer

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


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: https://lists.debian.org/20140703133234.GD1344@...

Reply | Threaded
Open this post in threaded view
|

Re: improvements to the Developers Reference maintenance workflows?

Marc Brockschmidt-4
In reply to this post by Lucas Nussbaum-4
Hi,

On Thu, Jul 3, 2014 at 10:27 AM, Lucas Nussbaum <[hidden email]> wrote:
> 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?

Yes.

Marc


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: https://lists.debian.org/CAA7ov5d3iNj9EoRpSevy8cNTcSS37NquBDN3uvdPjoZ-AwisHQ@...

Reply | Threaded
Open this post in threaded view
|

Re: improvements to the Developers Reference maintenance workflows?

Lucas Nussbaum-4
In reply to this post by Lucas Nussbaum-4
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


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: https://lists.debian.org/20140708141410.GA4270@...

Reply | Threaded
Open this post in threaded view
|

Re: improvements to the Developers Reference maintenance workflows?

Steve Langasek
On Tue, Jul 08, 2014 at 04:14:10PM +0200, Lucas Nussbaum wrote:

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

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

If we're going to have this in collab-maint, I think it's probably important
to ensure that git commits are announced on debian-policy.  Could someone
set this up?

Thanks,
--
Steve Langasek                   Give me a lever long enough and a Free OS
Debian Developer                   to set it on, and I can move the world.
Ubuntu Developer                                    http://www.debian.org/
[hidden email]                                     [hidden email]

signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: improvements to the Developers Reference maintenance workflows?

Bill Allombert-4
On Tue, Jul 08, 2014 at 09:25:53AM -0700, Steve Langasek wrote:

> On Tue, Jul 08, 2014 at 04:14:10PM +0200, Lucas Nussbaum wrote:
>
> > > 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?
>
> > 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.
>
> If we're going to have this in collab-maint, I think it's probably important
> to ensure that git commits are announced on debian-policy.  Could someone
> set this up?

Personnaly, I would prefer if they were sent to a dedicated mailing list.
There is enough traffic on debian-policy as it is.

Cheers,
--
Bill. <[hidden email]>

Imagine a large red swirl here.


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: https://lists.debian.org/20140708181222.GD8691@yellowpig

Reply | Threaded
Open this post in threaded view
|

Re: improvements to the Developers Reference maintenance workflows?

Raphael Hertzog-3
Hi,

On Tue, 08 Jul 2014, Steve Langasek wrote:
> If we're going to have this in collab-maint, I think it's probably important
> to ensure that git commits are announced on debian-policy.  Could someone
> set this up?

Done.

On Tue, 08 Jul 2014, Bill Allombert wrote:
> Personnaly, I would prefer if they were sent to a dedicated mailing list.
> There is enough traffic on debian-policy as it is.

The average number of commits on developers-reference is very low, and
those mails are easy to filter with procmail if they are noise for you.

Thus I went ahead.

Cheers,
--
Raphaël Hertzog ◈ Debian Developer

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


--
To UNSUBSCRIBE, email to [hidden email]
with a subject of "unsubscribe". Trouble? Contact [hidden email]
Archive: https://lists.debian.org/20140708185516.GA4658@...