kicad-developers team mailing list archive

[Marco Ciampa <ciampix@xxxxxxxxx>]

On Wed, Nov 22, 2017 at 02:55:35PM +0100, Maciej Sumiński wrote:
> On 11/22/2017 02:48 PM, Marco Ciampa wrote:
> [snip]
> > Please please please,
> > 
> > when some new feature is accepted (code merged in master branch), either
> > write it in the dev (master) branch of the documentation or somewhere to
> > enable doc writers to describe the new feature... (wiki? txt in the
> > source code? Bug Report?)
> > 
> > I think that a simple description in a bug report is the easiest way to
> > assure that new features get correctly described in the docs.
> > Parsing dev ml messages for these "hints" is IMHO unmanageable...
> > 
> > TIA
> > 
> 
> Hi Marco,
> 
> I thought we are supposed to use tags in commit messages (NEW, CHANGE)
> [1]. I can create a bug report in the documentation repository, if this
> is the preferred way. If so, then I suppose it should be made a policy.

Yes that was decided for compiling a "Changelog" like list of "What's
new" info directly extractable from git log messages in such a way that
upgraders and new adopters are eager to read and to point doc writers to
the matter that should be fully described elsewhere.

The thing is: the description of new functions hardly fits in a git
commit message. The [dev|author|helper] that wants to help
clarify/describe it througly needs more space.

He/she can obviously write directly to the source documentation but,
wanting to help the developers that prefer to write C++ code instead of
English, a simple Bug Report should go. Linking the commit message (NEW,
CHANGE) with a "see BR #NN" could help finding the longer description
that could be expanded in the manual.

> I am afraid it might be hard to follow for occasional patch submitters,
> should it be the committer responsible for creating a bug report?

I do not really know ... but if you decide that it would be not a big
burden to the commiter(s) this would be ideal.

Having a direct link of the bug report here:

> 1. https://git.launchpad.net/kicad/commit/?id=527c6f0014b03

would nicely fit IMHO...

But _please_ read these messages as a brainstorming / suggestion in an
RFC mode.

I am still trying to figure out how to better organize the flux of
information to make the documentation effort more straightforward and
efficient.

Any comment/suggestion is very welcome!

TIA

--


Marco Ciampa

I know a joke about UDP, but you might not get it.

------------------------

 GNU/Linux User #78271
 FSFE fellow #364

------------------------