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