kicad-developers team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

OK thanks, I will add some info to that doc in a PR.

-Jon

On Tue, Nov 28, 2017 at 12:01 PM, Wayne Stambaugh <stambaughw@xxxxxxxxx>
wrote:

> 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>
> >
> >
>