kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxx>]

On 11/09/2017 09:46 PM, hauptmech wrote:
> A URL into the documentation would probably lessen the friction of
> locating exactly what section of documentation needs fixing. Dev's
> changing user facing stuff will be familiar with (if not actively
> stubbing out, or updating the docs) it so it seems a reasonable ask.
> 
> CHANGED: Synopsis. url#section

I'm OK with this assuming the documentation actually exists.

> 
> Consider just one keyword (CHANGE, or FEATURE) so we are not doing "git
> log --grep=CHANGE|NEW|REMOVED"

This would be too limiting for generating change log extraction scripts.
 I could reducing it to NEW and CHANGE but anything less than that
doesn't make sense for generating change logs.

> 
> On 10/11/17 05:44, Wayne Stambaugh wrote:
>> I like this idea as well.  It's simple and easy to remember.  If there
>> are no objections, I will updated the commit message policy to add NEW,
>> CHANGED, and REMOVED tags and a brief explanation of when each tag
>> should be used.  Is there any special formatting that we want to use
>> with these tags to make life easier for folks trying to extract
>> information using scripts?  Rather than adding the tag to the end which
>> may be a bit limiting, I was thinking it may make more sense to add the
>> tag to the beginning of the description of the change separated by empty
>> lines.  It could look something like this.
>>
>> Major rewrite of some existing feature.
>>
>> NEW: The feature adds support for X, Y, and Z operations.
>>
>> REMOVED: The feature no longer supports the foo operation.
>>
>> CHANGED: The feature operations bar and baz now require manual
>> frobnication.
>>
>> If anyone has any better ideas, now is the time.
>>
>> Cheers,
>>
>> Wayne
>>
>> On 11/9/2017 11:06 AM, Maciej Sumiński wrote:
>>> 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
>>>>
>>>
>>>
>>>
>>> _______________________________________________
>>> 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