Skip to content

Latest commit

 

History

History
54 lines (51 loc) · 3.47 KB

README.md

File metadata and controls

54 lines (51 loc) · 3.47 KB
Raw

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.