Kotlin Project Model Design Documentation 1.0-master Help

Root page

Welcome to the design documentation about Kotlin Project Model!

TL;DR how to read this document

  • We encourage you to use GitHub Discussions and GitHub Issues for yout feedback on the docs
    • You're not obliged to use GitHub. Feel free to reach us (@dsavvinov in particular) on Slack, or wherever it is convenient for you.

    • You will help us greatly though if you use GitHub, because it allows to keep all discussions documented, persisted in one place, it allows reopening them, it allows cross-referencing discussions and code, etc.

  • It will be hard to read linearly from top to bottom due to sheer amount of cross-references; won’t do anything about it

  • Everything might change yadda-yadda

Goals/principles

  • Provide a basis on which anyone can suggest an improvement/change without much handwaving

  • Completeness and exactness of information >>> comprehensiveness. It’s better to write a correct, albeit hard-to-understand sentence, rather than omit some detail for the sake of brevity.

  • Motivation/reasoning matters

  • Gray areas/underdesigned areas should be highlighted explicitly

  • All discussions are expected to be resolved. Ideally, the outcome of the discussion are fixes to the respective text. E.g.: “Hey folks, I think this sentence isn’t correct” → discussion follows up → the sentence is fixed.
    • If the raised question is too big to be resolved via text discussion, then it’s strongly advised to extract it as the separate topic (e.g. in https://jetbrains.quip.com/s7uVAtrWSsP3#QEKACANzBLm), add link to it and work on it, then proceed with filling the gaps/gray areas as usual

    • Consequence: Facts and information shouldn’t be stored in comments. E.g., putting something like “TODO: this sentence is not entirely correct” in comments isn’t allowed. Instead, it should be noted inline in text.

Non-goals

  • Linearly readable representation of information. Refer to Kotlin MPP Project Model 2.0 (document shared with Google and other external partners (https://docs.google.com/document/d/1LLnXfh3kzajYupN7IoKgX6lFpR5z-IZ0MVGFPYuDr9k/edit?usp=sharing)) for an attempt to have a readable and comprehensible explanation. Other documents which represent a comprehensible “view” on that massive amount of information might follow-up (e.g. a user-targeted step-by-step explanation with gradual increase of complexity)

Notation

  • KPM stands for Kotlin Project Model.

    • Yeah, it was formerly known as PM2.0, but numbers and dots play badly when used in sources/around it (package names, prefixes for source entities, branch names in Git, etc.)

    • It is advised to use KPM from now on.
    • Yeah, it is a mess. Sorry.

  • Statements which call for an additional discussion will be marked with footnote markers, like this: 1

  • areas with known design issues/holes will be marked in the following way (think about them as of // FIXME for design docs)

  • Some design questions span throughout multiple topics. E.g., decision whether we allow to publish expects without actuals influences multiple parts of KPM, including definitions of module, dependencies, etc. Such big design questions are assigned with a special short tag, like #Test-production code arrangement, and respective tags are mentioned in respective parts. This allows quick search of all areas which are influenced by a specific design question.

Last modified: 20 May 2021