LargeScaleChanges
TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate
Preamble
Large scale cosmetic changes to the code-base are necessary to ensure that the code-base continues to look better, read more cleanly, and adapts to modern times.
However large cosmetic scale changes also can significantly hinder those who are maintaining, and back-porting features and fixes to older versions.
In consequence the timing and content of large scale cosmetic changes is really important.
What is a Large Scale change
Consider a change such as renaming an API - if this API is used in a handful of files - this is quite a small scale change. If however, a subsequent patch renames another API - for another handful of files - then we have a slightly larger change. If continued a fifty times, this becomes collectively a rather large change.
Large scale changes are good - we want to change and improve the code, and people shouldn't feel constrained when they are actively improving, fixing or adding functionality to the code - that is very important.
Large Scale Cosmetic changes
These are the bad guys, but at the same time nice tasks for a beginner - this is large scale change that adds no feature, or function, or fix - but is simply moving the code around, or making it look, and read better.
Some of this type of change are particularly problematic - for example splitting and merging files, large scale renames of methods, fiddling with namespacing, or wide-spread white-space changes.
There is no particularly hard line here either - some people are convinced that replacing every boost::foo with a std::foo is a vital functional improvement, others are more of the view that it is more cosmetic. The general rule is, do not make such changes, unless it is defined as an EASYHACK.
Cosmetic changes are also good - but making life easy for those doing the much harder, and much more useful back-porting of patches is socially vital.
Some guidelines
Back-porting decreases in frequency the longer the stable branch has been around - at the branch-point almost everything goes into both master and the fresh branch; over time that decreases. So: Don't apply large scale cosmetic changes to master until after X.Y.2
Splitting, re-organizing and renaming files also creates pain for everyone and makes git logs, and blame hard to trace. This should also be done in the month just before the major branch point, ideally with patches created just beforehand.
Very large cosmetic cleanups that are script-able; eg. wholesale class and method renaming - should be done just before the branch point, and in a script checked into git that can be run by a release engineer. bin/rename-sw-abbreviations.sh is a good example of this sort of script.
Easy Hacks - why cosmetic changes ?
Bugzilla contains several bugs, typically classified as EASYHACKS, that require changes in a large number of files.
A typical bug is Bug 39674 - find / fix all German spellings in internal APIs
This is a simple search/replace which of course appeals to new contributors. As with all easy hacks - the function of the Easy Hack is not to immediately fix all instances of the bug, creating a gigantic cosmetic change (and closing the easy hack).
The intention of Easy Hacks is to get people involved in the project, and familiar with our process by getting a single, simple, small change included.
After this - instead of solving all instances of this problem it is far better to move onto picking some interesting bug, or feature to work on - or a harder Easy Hack. In this way you can grow into a vital, core developer, and start to appreciate the challenges of back-porting and maintaining your work on stable branches.
Failing that - if you really feel you need to close the ESC bugs created to get people involved with the project by completely fixing them - please ensure that you file an equivalent, well researched easy hack to replace that, and also submit your large scale cosmetic change at a convenient time cf. the above guidelines. Thanks !