Re: [GLISS] - alternative viewpoint

[Graham Percival]

On Sat, Sep 22, 2012 at 01:42:46PM +0200, Marc Hohl wrote:
> Am 21.09.2012 11:00, schrieb David Kastrup:
> >A user interface change without documentation or regtest is dead code.
> Regtests are somewhat mandatory:
> 
> http://lilypond.org/doc/v2.17/Documentation/contributor/write-regression-tests
> 
> but the documentation work is not a "you'll have to do" but rather a
> "it would be nice if" rule.

Yes, that's deliberate.  There's no point holding back programmers
who are not comfortable writing code.

> But at least there should be some automatism that raises an
> issue "xyz-needs documentation" whenever a patch has made it
> through the revision process but lacks of a proper documentation
> (*if* the patch concerns a major change, like my bar line stuff).

There's already some sort of this:
  git diff -u -r release/2.14.0-1 -r release/2.15.95-1 \
    input/regression/
then check if the new features were added to the docs.

It's already listed in the Major release checklist, although we
skipped over it at Waltrop.

> In my case, I *will* tackle documentation if nobody else wants to,
> because I know that this feature needs a change in the docs, but
> the patch itself has undergone quite 60+ comments (part 1 and 2
> altogether), so when the documentation work would have been
> included yet, I think we would be at 100+ (or I had already given
> up ;-).

I suggest doing the documentation as a separate patch.

> >We might as well remove it before the next stable release.

No.

> So I repeat my proposal again: a developer *must* include
> regression tests, he *should* do the doc work, but if he feels
> not very comfortable at writing some paragraphs for the
> docs, he should *have to* raise an issue about that.

I don't think that piling up a bunch of issues will help.  Rather,
we should try to not alienate our existing documentation writers,
and once that's done, recruit new doc writers.  It wouldn't be
hard for somebody to write docs for every new feature between each
release.

- Graham