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
