matthijskooijman
commented
6 years ago +1 for removing the changelogs. I've found that the big comment block is confusing for students when using the examples in teaching, where the changelogs serve no purpose at all.
This was previously discussed at https://github.com/arduino/Arduino/pull/5356 but, since that PR is closed and there has been no progress, I think it needs a dedicated issue.
The current convention is the author of a change to one of the example sketches may add to the changelog in the comment at the top of the file. This convention is followed quite inconsistently. Sometimes significant changes are made without a changelog update. Other times the change log is updated for minor changes (example(. So the information contained is of no actual use other than attribution.
Inevitably the changelogs grow over time. This text is of no interest to 99.999% of the users, yet is encountered before they can even get to the code. This could cause confusion for beginners and unnecessary scrolling for everyone else.
I just don't see any benefit to this. If people want to examine the change history the commit log is far superior. Contributors are already given credit in the commit history, the "Contributors" page of the repository, and significant contributions may also be noted in the release notes.
Some proposals for dealing with this, in order of preference:
cmaglie also made this comment:
I take it this means simply leaving a list of author names. That seems quite reasonable. It provides attribution for those who care without adding two lines of comments for every change.
Progress on the previous discussion stalled with this comment from @cmaglie:
There has been no news since on whether permission to proceed was granted.
Regarding it being a big job: I previously volunteered to do all the work and submit pull requests. That offer still stands. I just need the go ahead and decision on which approach to take and I'll get working on it.
If this is done, it would also make sense to remove the recommendation for this practice from the "Explain the code at the start" section of the Arduino style guide (https://www.arduino.cc/en/Reference/StyleGuide#wikitext:~:text=Explain%20the%20code%20at%20the%20start).