Skip to content

Files

Latest commit

8cb8c70 · Dec 17, 2024

History

History

src

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
Dec 17, 2024
Aug 5, 2024
Mar 28, 2024
May 17, 2024
Oct 29, 2024
Jun 12, 2024
Dec 10, 2024
Nov 12, 2024
Sep 30, 2024
Aug 24, 2022
Aug 19, 2024
Dec 10, 2024
May 29, 2024
Nov 28, 2024
Dec 10, 2024
Jul 2, 2019

Rules for the ILIAS namespace and the ./src-Folder

This rules are to be understood according to RFC2119.

  1. The ILIAS-namespace is meant to contain library-like functionality with clear boundaries and purpose. This means:
    1. All code in the ILIAS-namespace MUST provide cross sectional functionality. There might be some change in this rules later on to port component specific code to the ILIAS namespace as well, but for the moment the component specific code resides in the Services- and Modules directories. This means that the code for a hypothetical general notification system would be going to the ILIAS-namespace, while implementation specifics for the notifications of a course should go to Modules/Course.
    2. Every subnamespace of ILIAS is considered to represent one library of ILIAS.
  2. The ./src-Directory is the root of the ILIAS-namespace. All directories and files in the ./src-Directory MUST comply to PSR-4, where the vendor-namespace is ILIAS.
  3. Classes, interfaces and traits MUST NOT have an il-Prefix like the classes in Services and Modules have.
  4. Library-like code SHOULD be added to the src-Folder and not to the Modules- or Service-directory.
  5. Anyone who wants to make additions to the ./src-folder SHOULD discuss them with the Technical Board in advance.
  6. Libraries SHOULD contain a README.md on the top-level, that explains the purpose and design of the library and gives usage examples.
  7. All libraries MUST expose a clear public interface to their consumers. Every class, interface or trait on the top level of the library is considered to be a part of the public interface, as well as all entities that are reachable via entities on the top level.
  8. The public interface of the libraries MUST be documented with Doc-Blocks. Classes, interfaces or traits SHOULD be documented with at least one sentence telling the purpose of the entity - repeating the class's name is not enough. Functions and Methods MUST at least be documented with one sentence giving the semantics and the in- and outputs in PHP-Doc-format. This MAY be ommited (in the respective parts) if the docs would not further clarify information given by the functions's name or explicitly distinguishable typehinting. Example: "public function withTitle(string $title): myObject" does not need a Doc-Block, but "public function calculate(array $params)" does!
  9. Libraries MUST NOT be subject to a breaking change in an ILIAS release-branch.
  10. Breaking changes to a library MUST be announced at least one month in advance on the Jour Fixe. Breaking changes to a library MUST be made in the trunk.
  11. Libraries SHOULD contain a CHANGELOG.md on the top-level, that informs about the history of the library. The file should enable users of the library to incorporate the changes.
  12. Libraries SHOULD provide automated tests for PHPUnit, where the tests MUST be put in a subdirectory of ./tests, which has the same name as the library.
  13. Libraries SHOULD be parametrized on their IO-operations. That means, e.g., that libraries should not use echo directly or retrieve a database from a global but instead get dependencies like that via injection.
  14. Libraries SHOULD NOT maintain an implicit internal state. All internal states SHOULD be made explicit. This means, e.g., that the usage of globals, static variables and the Singleton-pattern are prohibited.