search

aws / amazon-freertos

DEPRECATED - See README.md
https://aws.amazon.com/freertos/
MIT License
2.54k stars 1.1k forks source link

maybe don't put the version number in every single file? #67

Closed jrr closed 6 years ago

jrr commented 6 years ago

The sources have headers like this:

/*
 * Amazon FreeRTOS V1.4.1
 * Copyright (C) 2017 Amazon.com, Inc. or its affiliates.  All Rights Reserved
...

Which results in diffs like https://github.com/aws/amazon-freertos/commit/8b6f1577b7da0712c6b8e3fdde2c18fbf1e6cf69 . If you're looking for what changed in that release, good luck!

In that particular release, there were 3 meaningful changes among 246 touched files:

~/r/r/amazon-freertos ((v1.4.1))> git show v1.4.1 --oneline --stat |grep -v " 2 "
tag v1.4.1

Version 1.4.1
8b6f157 Release Version 1.4.1
 CHANGELOG.md                                                   | 10 ++++++++++
 lib/ota/portable/pc/windows/aws_ota_pal.c                      |  8 ++++----
 tests/pc/windows/common/config_files/aws_test_ota_config.h     | 10 +++++-----
 246 files changed, 262 insertions(+), 252 deletions(-)

And in case you were under the illusion that comment headers like these can be accurately maintained,

I can understand if you are required to include the license and date in comment headers, but is the version number really necessary?

In order to prevent this from being just a rant, I'll offer a suggestion: you could slightly reduce the pain on developers if you update the headers in a separate commit, not squashed together with code changes.

alexa-noxon commented 6 years ago

Hi Jrr,

I’m sorry for the difficulty that the versioning has caused.

I’d like to explain the philosophy behind it so that the changes seem a little less arbitrary (acknowledging that this will not change the large number of files in each diff!). • Whenever a the version of Amazon FreeRTOS is changed, all files in the demos folder have their version number incremented to match the Amazon FreeRTOS version, regardless of whether that particular file was changed or not. • The library files are versioned separately than the main Amazon FreeRTOS version--- these files are only updated if a file in the library is modified. • Finally, library portable layer files are versioned independently, and will only be incremented if the portable file is modified.

The top bullet explains why the diff you have pointed out includes so many files, and the second 2 bullets are (at least part of) the reason that there are many different versions attached to different files in the same release.

A version number is included in each file for a couple of reasons: • One is that FreeRTOS is distributed via many different channels and vendors beyond Github. Often the entire code base is not distributed, just selected libraries, and not all of these distribution channels provide a version history or context. • Historically some application writers have performed mix-and-match updates where some libraries are updated but not all, and having the version number allows support to more quickly determine what code combination is being used by the application.

Thanks for your suggestion – I will pass on your idea of doing 2 commits (one for the content changes and one for the header/version changes) on up the chain.

Best, Alexa

jrr commented 6 years ago

Thanks for the detailed response, Alexa. Two commits would help a lot.