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 <[email protected]> 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 <[email protected] > > <mailto:[email protected]>>: > > > > 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 > > <[email protected] <mailto:[email protected]>> 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 > > >>>> <[email protected] > > <mailto:[email protected]>>: > > >>>> > > >>>>> 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 < > > >>>>>> [email protected] > > <mailto:[email protected]> > > <mailto:[email protected] > > <mailto:[email protected]>>>: > > >>>>>> > > >>>>>> > > >>>>>> 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 : > > [email protected] > > <mailto:[email protected]> > > >>>>>> <mailto:[email protected] > > <mailto:[email protected]>> > > >>>>>> 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 : [email protected] > > <mailto:[email protected]> > > >>>>>> <mailto:[email protected] > > <mailto:[email protected]>> > > >>>>>> 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 : [email protected] > > <mailto:[email protected]> > > >>>> 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 : [email protected] > > <mailto:[email protected]> > > >>> 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 : [email protected] > > <mailto:[email protected]> > > >> 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 : [email protected] > > <mailto:[email protected]> > > > 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 : [email protected] > > <mailto:[email protected]> > > 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 : [email protected] > > <mailto:[email protected]> > > 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 Post to : [email protected] Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
