Dear ILIAS-developers and -admins,
we would like to inform you about the introduction of a new coding style guideline for ILIAS-code [1], why, how and when we want to introduce it and how you will be involved in this process.
The coding style guideline we will introduce is the well known PSR-2 [2] plus some rather minor additions. We believe it to be very valuable for projects to stick to a common style: it is easier to read code with a consistent layout, it is easier to find your way around in code if you aren't distracted from differences in styling and, finally, we all have one rather minor point less to argue about. Currently there already exists a coding style guideline for ILIAS, but it isn't followed consistently. We further believe that the value of coding style guidelines doesn't only apply to single projects, but also to a language community as a whole. If people share a common guideline when writing PHP, the benefits will also apply when switching projects and newcomers to ILIAS won't be distracted by ILIAS specialties in the coding style. To introduce a consistent coding style that also follows standards of the PHP-community, we decided to introduce PSR-2 with some additions.
We intentionally only focussed on directions regarding formatting of code and dismissed questions regarding naming or patterns like "How to name interfaces or classes?" or "When to use early return?". We feel that these require more effort in discussions and want to pick low hanging fruits via this proposal first.
This guideline replaces the one in the development guide [3].
We know that this introduction of a coding style guideline will cause some disruption, among core-developers as well as among devs who maintain patched versions of ILIAS. We still feel that having no implemented guideline is not an option anymore and try to make the move to PSR-2 plus additions as painless as possible. The introduction will benefit us all long-term.
The introduction will proceed in three phases:
Starting in June 2019 every change in a maintained ILIAS-version or the trunk must be made after the coding style in the targeted file(s) is fixed. The style fixes must be made in a single commit with the message "CS fix". The desired changes should be made afterwards and in one or many separate commits. If I would, for example, want to fix a bug in Modules/StudyProgramme/classes/class.ilObjStudyProgrammeGUI.php I would first apply the fix to the coding style to the file, commit it with the message "CS fix", then make the desired changes to fix the issue, and also commit them. Maintainers may also move a complete component in all maintained branches and the trunk to the new style at their own discretion. This will gradually move some parts of all of our branches to the new coding style while maintaining the possibility to find a responsible person via git blame and cherry-picking changes from other branches.
Once the beta-release is ready and branched in October, we will apply the new coding style to the rest of our codebase in all maintained branches and the trunk. This will be done via one big commit per branch. This will break patches, PRs that are open at that point in time and also git blame for parts of the codebase that haven't been modified before. Please be aware that this will happen and reserve time for required actions accordingly.
After this single commit that fixes the rest of our codebase, our CI-server [4] will automatically check if new code respects our coding style guideline. We are looking into the details regarding the necessary measures to ensure the whole ILIAS code base keeps respecting the guideline also in the future. One important elements will be the actions taken by the CI-server if code does not respect the guideline.
To ease the introduction and also maintain the coding style in the long-run, we will supply you with some material:
* A documentation that shows how you could introduce tooling on your dev-machine that automatically maintains the coding style. * A configuration for PHPStorm for the coding style. * A shell-script that fixes the coding style for a single file or a directory.
We are exited to make this move with you and look forward to have a consistent style in out codebase. If you have any doubts, questions or suggestions, feel free to contact us at tb@lists.ilias.de
Shout out to Nils Theen (@legionth) for pushing this issue. Thanks!
Best regards!
Stephan Winiker
on behalf of the Technical Board of the ILIAS Society
[1] https://github.com/ILIAS-TechnicalBoard/ILIAS/blob/trunk_coding_style/docs/d... [2] https://www.php-fig.org/psr/psr-2/ [3] https://docu.ilias.de/goto_docu_pg_202_42.html [4] https://travis-ci.com/ILIAS-eLearning/ILIAS