kicad-developers team mailing list archive

[Maciej Sumiński <maciej.suminski@xxxxxxx>]

I am in favor of including the information in commit messages. In the
simplest version, one can simple append "CHANGE" at the end of a commit
message. If we follow this scheme, then to get a changelog it is enough
to execute "git log --grep=CHANGE". One can also modify the query to get
changelog for different periods.

It is a tiny effort on the developers side which significantly helps
people willing to work on the documentation, therefore I think it is
worth pursuing. The only possible problem I see here is to get into the
habit, but we did well with "Fixes".

Regards,
Orson

On 11/09/2017 01:40 PM, Nick Østergaard wrote:
> I didn't mean to indicate that one shall not write useful commit messages
> in the kicad source repo. The start of this topic was how to make sure to
> keep the doc up to date. This is what I was trying to comment on. Here it
> is better to track the work where it is to be done, in the kicad-doc repo.
> That does not hinder anyone from grepping the kicad commit log for new
> features, when one gets the urge to create documentation. This shall of
> course not hinder anyone who submits a feature to kicad to also submit
> documentation updates for it either.
> 
> When we release I expect a release note to be composed that will describe
> the new features as we did with http://kicad-pcb.org/post/release-4.0.0/
> 
> 2017-11-09 12:39 GMT+01:00 Kristoffer Ödmark <kristofferodmark90@xxxxxxxxx>:
> 
>> That doesnt sound like a good idea, when adding patches, just having to
>> add a line or two to the commit message seems best, and I imagine the news
>> or changelog file is just there to later help the kicad-doc repo to do a
>> proper changelog. Having to go to a new repo seems a bit more annoying.
>>
>> Or skip the file totally this time, and just enfore the commit messages.
>> This way this will not be such a hassle next time one wonders what have
>> changed between versions.
>>
>> On 11/09/2017 11:05 AM, Nick Østergaard wrote:
>>
>>> I think this might be better handled as bugs on the kicad-doc repo. Then
>>> everyone can contribute easily and we can track it for the documentation,
>>> where the info is to be used anyways. For now label them new_kicad_feature
>>> if it is.
>>>
>>> 2017-11-09 10:54 GMT+01:00 Kristoffer Ödmark <
>>> kristofferodmark90@xxxxxxxxx <mailto:kristofferodmark90@xxxxxxxxx>>:
>>>
>>>
>>>     I think for this to start happen, a decision has to be made, and
>>>     enforced by everyone with commit access to the repo.
>>>
>>>     Bugfixes need not be tagged like this. Major changes only.
>>>
>>>     I still think a we should start collect a list in the repo with
>>>     changes from kicad 4 up to the point this commit message policy is
>>>     set. I for one love reading changelogs when upgrading, and I think
>>>     the users are expecting this as well, and it probably will be useful
>>>     in the FOSDEM presentation :)
>>>
>>>
>>>     On 11/04/2017 01:53 AM, Wayne Stambaugh wrote:
>>>
>>>         On 11/3/2017 8:54 AM, Maciej Sumiński wrote:
>>>
>>>             On 11/03/2017 11:30 AM, Kristoffer Ödmark wrote:
>>>
>>>                 I think starting small would be best in this case. The
>>>                 least needed
>>>                 would be a "News" File, that is always refering to kicad
>>>                 stable.
>>>
>>>                 I propose the same way that patches with policy errors
>>>                 are rejected,
>>>                 patches that introduces new functionality or change of
>>>                 existing
>>>                 functionality are required to add to the News file, max
>>>                 one line. Just
>>>                 something like this, I would like markdown formatting.
>>>
>>>
>>>                 Changes from Kicad 4
>>>                 =
>>>
>>>                 NEW: Pcbnew now supports clipboard copy/paste
>>>                 CHANGE: Delete button now removes entire trace, not just
>>>                 a segment
>>>                 CHANGE: Icons in toolbar are improved
>>>                 REMOVED: Autorouter no longer exists
>>>
>>>
>>>                 This style could also be applied in the git commit
>>>                 message, making it
>>>                 easy to compile by something such as 'git log | grep
>>> "NEW:"'
>>>
>>>                 But since that is lacking, I think starting a new file
>>>                 is best.
>>>
>>>
>>>             I vote for git commit messages following a specific format
>>>             (could be
>>>             NEW:/CHANGE:/REMOVE: lines) to easily create change logs. It
>>>             is much
>>>             easier to see with git what has changed in a specific period
>>>             of time.
>>>             With NEWS file you would need at least put dates there to be
>>>             able to do
>>>             that (or see with git when a specific line has been added).
>>>
>>>             I know that ideally the user documentation should be updated
>>>             together
>>>             with the code, but on the other KiCad changes so fast, so
>>>             there might be
>>>             a lot of wasted time spent on changing the documentation and
>>>             updating
>>>             screens that might be invalid in a week or two. For sure the
>>>             documentation should be refreshed for a stable release.
>>>
>>>             Regards,
>>>             Orson
>>>
>>>
>>>         I'm not opposed to this idea but it should be used sensibly.
>>>    Not all
>>>         new, changed, or removed code will require documentation
>>> changes.  I
>>>         would also prefer it not be in the first line of the commit
>>> message
>>>         unless the commit message is only one line.  It's already
>>>         difficult to
>>>         fit a descriptive commit title with only 72 characters.
>>>
>>>         Cheers,
>>>
>>>         Wayne
>>>
>>>         _______________________________________________
>>>         Mailing list: https://launchpad.net/~kicad-developers
>>>         <https://launchpad.net/~kicad-developers>
>>>         Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
>>>         <mailto:kicad-developers@xxxxxxxxxxxxxxxxxxx>
>>>         Unsubscribe : https://launchpad.net/~kicad-developers
>>>         <https://launchpad.net/~kicad-developers>
>>>         More help   : https://help.launchpad.net/ListHelp
>>>         <https://help.launchpad.net/ListHelp>
>>>
>>>
>>>     --       -Kristoffer
>>>
>>>
>>>     _______________________________________________
>>>     Mailing list: https://launchpad.net/~kicad-developers
>>>     <https://launchpad.net/~kicad-developers>
>>>     Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
>>>     <mailto:kicad-developers@xxxxxxxxxxxxxxxxxxx>
>>>     Unsubscribe : https://launchpad.net/~kicad-developers
>>>     <https://launchpad.net/~kicad-developers>
>>>     More help   : https://help.launchpad.net/ListHelp
>>>     <https://help.launchpad.net/ListHelp>
>>>
>>>
>>>
>> --
>>  -Kristoffer
>>
> 
> 
> 
> _______________________________________________
> 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