kicad-developers team mailing list archive

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

The list of changes are to be mentioned in the release note post on the
website. I suggest to send pull requests to:
https://raw.githubusercontent.com/KiCad/kicad-website/master/content/post/release-5.0.0.adoc

Currently that doc just contains some of the important changes that I have
seen be merged, but probably not all.

To make it an actual release note. If there are specific things that needs
to be updated in the docs, please create a pull request and/or report an
issue on the doc repo.

2017-11-28 17:24 GMT+01:00 Jon Evans <jon@xxxxxxxxxxxxx>:

> So, since this commit message method won't work for all the existing
> commits, where should we start to collect a list of features/changes from
> 4.0?
> If the doc repository is a good place for this, I can start something
> there and send a patch.
> It looks like changelogs are not currently part of the documentation
> structure, so I would propose to create a new place for them, then we can
> have a "New in 5.0" document.
>
> If everyone who contributed features/changes to 5.0 can put a simple list
> of these features/changes into one place, then it will be easy to expand
> that to a full set of documentation.
>
> -Jon
>
> On Fri, Nov 10, 2017 at 1:04 PM, Wayne Stambaugh <stambaughw@xxxxxxxxx>
> wrote:
>
>> 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
>>
>> _______________________________________________
>> 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
>
>