kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxx>]

I'm not sure we want to include what's new in the documentation.  I know
other projects do it but does it really fall under the scope of
documentation?  The blog post works for me.  This is where we have made
new feature and release announcements in the past.

On 11/28/2017 11:55 AM, Nick Østergaard wrote:
> 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
> <mailto: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 <mailto: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/
>         <http://kicad-pcb.org/post/release-4.0.0/>
>         >>>>
>         >>>> 2017-11-09 12:39 GMT+01:00 Kristoffer Ödmark
>         >>>> <kristofferodmark90@xxxxxxxxx
>         <mailto: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>
>         <mailto: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>
>         >>>>>>          <https://launchpad.net/~kicad-developers
>         <https://launchpad.net/~kicad-developers>>
>         >>>>>>          Post to     :
>         kicad-developers@xxxxxxxxxxxxxxxxxxx
>         <mailto:kicad-developers@xxxxxxxxxxxxxxxxxxx>
>         >>>>>>          <mailto:kicad-developers@xxxxxxxxxxxxxxxxxxx
>         <mailto:kicad-developers@xxxxxxxxxxxxxxxxxxx>>
>         >>>>>>          Unsubscribe :
>         https://launchpad.net/~kicad-developers
>         <https://launchpad.net/~kicad-developers>
>         >>>>>>          <https://launchpad.net/~kicad-developers
>         <https://launchpad.net/~kicad-developers>>
>         >>>>>>          More help   :
>         https://help.launchpad.net/ListHelp
>         <https://help.launchpad.net/ListHelp>
>         >>>>>>          <https://help.launchpad.net/ListHelp
>         <https://help.launchpad.net/ListHelp>>
>         >>>>>>
>         >>>>>>
>         >>>>>>      --       -Kristoffer
>         >>>>>>
>         >>>>>>
>         >>>>>>      _______________________________________________
>         >>>>>>      Mailing list:
>         https://launchpad.net/~kicad-developers
>         <https://launchpad.net/~kicad-developers>
>         >>>>>>      <https://launchpad.net/~kicad-developers
>         <https://launchpad.net/~kicad-developers>>
>         >>>>>>      Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
>         <mailto:kicad-developers@xxxxxxxxxxxxxxxxxxx>
>         >>>>>>      <mailto:kicad-developers@xxxxxxxxxxxxxxxxxxx
>         <mailto:kicad-developers@xxxxxxxxxxxxxxxxxxx>>
>         >>>>>>      Unsubscribe :
>         https://launchpad.net/~kicad-developers
>         <https://launchpad.net/~kicad-developers>
>         >>>>>>      <https://launchpad.net/~kicad-developers
>         <https://launchpad.net/~kicad-developers>>
>         >>>>>>      More help   : https://help.launchpad.net/ListHelp
>         <https://help.launchpad.net/ListHelp>
>         >>>>>>      <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>
>         >>>>
>         >>>
>         >>>
>         >>>
>         >>> _______________________________________________
>         >>> 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>
>         >>>
>         >> _______________________________________________
>         >> 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>
>         >
>         >
>         >
>         > _______________________________________________
>         > 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>
> 
>         _______________________________________________
>         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>
> 
> 
> 
>     _______________________________________________
>     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>
> 
>