kicad-developers team mailing list archive

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