kicad-developers team mailing list archive

[Nick Østergaard <oe.nick@xxxxxxxxx>]

We could also set jenkins up to create an issue on the doc repo, triggered
by the keyword, and then we can handle the documentation effort and
discussion there. I can play with that.

2017-11-22 16:27 GMT+01:00 Maciej Sumiński <maciej.suminski@xxxxxxx>:

> On 11/22/2017 04:01 PM, Marco Ciampa wrote:
> > 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.
>
> Commit messages may fit a lot of text inside. When you run 'git log
> --grep' you will get full commit message, so I imagine we can simply put
> the right description there. For example:
>
> -------- 8< --------
> NEW: Copy/cut/paste graphical items in the library editor
> Since now users can cut/copy/paste individual items of a edited symbol.
> It can be done via a hot key or right click context menu.
>
> CHANGED: More coherent icons on the library editor toolbar
> All save icons, but one (save part) had arrows pointing down. 'Save
> part' icon has been modified to follow this rule.
> -------- 8< --------
>
> I know there are people complaining about too brief commit messages,
> perhaps this would enforce us to describe better the introduced changes.
>
> >> 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.
>
> I think it should be feasible, it is just a matter of developing a
> habit. It could be also a solution for cases when one forgets to include
> ADD/CHANGE/REMOVE tags in the commit message.
>
> > 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.
>
> Sure, I realize that. I just want us to pick the right way and commit to
> it (no pun intended).
>
> Cheers,
> Orson
>
> > 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
> >
> > ------------------------
> >
> >
> > _______________________________________________
> > Mailing list: https://launchpad.net/~kicad-developers
> > Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> > Unsubscribe : https://launchpad.net/~kicad-developers
> > More help   : https://help.launchpad.net/ListHelp
> >
>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp
>
>