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