kicad-developers team mailing list archive

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

To have a concrete text that we can discuss, I propose an update to the
Contribute->Developers page with the attached patch. What do you think?

Cheers,
Orson

On 11/22/2017 04:21 PM, Wayne Stambaugh wrote:
> On 11/22/2017 10:16 AM, Maciej Sumiński wrote:
>> On 11/22/2017 03:55 PM, Wayne Stambaugh wrote:
>>> On 11/22/2017 08:55 AM, 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.
>>>
>>> You are and you did.  Nice job!  The real question is how does this
>>> information make it from the source repo commit messages to doc devs so
>>> the docs can be updated accordingly?
>>
>> For example:
>>
>>   git log --grep="CHANGE[D]\?:\|REMOVE[D]\?:\|NEW:"
>>
>> I can turn it into an alias and add it to the same files that handles
>> 'git fixes' command. You can also extend the query with a date or a
>> commit hash. This way, once you enable the git alias configuration you
>> may type:
>>
>>   git changelog --since="1 Jan 2017"
>>
>> or
>>
>>   git changelog 527c6f001
> 
> Sorry about the miscommunication .  I am aware of how to extract the
> information from git but I meant how does this information get to the
> doc devs?  Are we expecting doc devs to periodically check the source
> repo or do we want to do something more sophisticated like sending a
> notice to the doc dev mailing list when a change is committed that
> requires changes to the docs?  I'm not saying this is what I want and
> I'm OK with whatever we decide, I'm just asking the question.
> 
>>
>>>>
>>>> I am afraid it might be hard to follow for occasional patch submitters,
>>>> should it be the committer responsible for creating a bug report?
>>>>
>>>> Regards,
>>>> Orson
>>>>
>>>> 1. https://git.launchpad.net/kicad/commit/?id=527c6f0014b03
>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> 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
>>>
>>
>>
>>
>>
>> _______________________________________________
>> 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
> 

From dde8e2364cf18e343153b2d77359713c13b29082 Mon Sep 17 00:00:00 2001
From: Maciej Suminski <maciej.suminski@xxxxxxx>
Date: Fri, 24 Nov 2017 17:07:12 +0100
Subject: [PATCH] contribute/developers: describe changelog tags

---
 content/contribute/developers.adoc | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/content/contribute/developers.adoc b/content/contribute/developers.adoc
index 4986c12..d9ed3ea 100644
--- a/content/contribute/developers.adoc
+++ b/content/contribute/developers.adoc
@@ -176,6 +176,43 @@ Afterwards you may mark commits using 'git fixes' command:
     git commit -a -m "Fixed a memleak"
     git fixes 12345678
 
+==== Changelog tags ====
+
+To facilitate following the code changes, please include a changelog tag to
+indicate modifications observable by the users. There are three types of
+changelog tags:
+
+- `NEW` to denote a new feature
+- `CHANGED` to indicate a modification of an existing feature
+- `REMOVED` to inform about removal of an existing feature
+
+There is no need to add changelog tags for commits that do not modify the way
+users interact with the software, such as code refactoring.
+
+When a commit with changelog tags is pushed, the committer should create a new
+issue in the link:https://github.com/KiCad/kicad-doc/issues[documentation
+repository] to notify the documentation maintainers. It is best to include a
+link to the commit containing the reported changes.
+
+An example commit message containing changelog tags (and bug fixes):
+
+    Eeschema: Adding line styling options
+    .
+    NEW: Adds support in eeschema for changing the default line style,
+    width and color on a case-by-case basis.
+    .
+    CHANGED: "Wire" lines now optionally include data on the line style,
+    width and color if they differ from the default.
+    .
+    Fixes: lp:594059
+    * https://bugs.launchpad.net/kicad/+bug/594059
+    .
+    Fixes: lp:1405026
+    * https://bugs.launchpad.net/kicad/+bug/1405026
+
+It is easy to extract the changelog using git commands:
+
+    git log -E --grep="ADD:|NEW:|REMOVE[D]?:|CHANGE[D]?:" --since="1 Jan 2017"
 
 === Pulling changes and rebasing
 
-- 
2.13.3

Attachment: signature.asc
Description: OpenPGP digital signature