kicad-developers team mailing list archive

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

Attachment: signature.asc
Description: OpenPGP digital signature