Splitting a large work to small git commits, should I update the README.md on each commit?

Question

I have made a design change to a contrib package on a large open-source project (TensorFlow).

I would like to commit my work in small, well defined, compiling commits.

Of course I will have updated the README.md to the new design. My question is how to do it:

• Update the README.md before the commits - code will not be synced with the README.md .
• Update the README.md after the commits - README.md will not be synced with the code.
• Update the README.md on each commit - tedious, but might be the best option.

Thanks.

Answer 1

Actually, there is no strict answer on your question. Generally you should discuss such things with other code contributors to your repository.

From my own experience I would highly recommend you to follow atomic commit convention , since there is sense of doing small high coupled commits.

According to it:

When using a revision control systems a common convention is to use small commits. These are sometimes referred to as atomic commits as they (ideally) only affect a single aspect of the system. These atomic commits allow for greater understandability, less effort to roll back changes, easier bug identification.

This approach allows you to guarantee your code is consistent on each commit you've made, and also makes much easier to undo unwanted things (using revert, hard reset, so on).

From that point of view last option you've mentioned is preferred.

Imagine that after some time you want to cancel one of your commits from the past, that indirectly forces you to update description that was written in different commit. It could be easier if you've made both changes related to each other in one commit.