From 131d9daa8f4fe66cf844f20a56388fdea852cb22 Mon Sep 17 00:00:00 2001 From: "Adolfo R. Brandes" Date: Sat, 14 Jun 2025 17:18:21 -0300 Subject: [PATCH] docs: update the slot naming ADR --- .../0009-slot-naming-and-lifecycle.rst | 23 +++++++++++-------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/decisions/0009-slot-naming-and-lifecycle.rst b/docs/decisions/0009-slot-naming-and-lifecycle.rst index 3735e13a..55557738 100644 --- a/docs/decisions/0009-slot-naming-and-lifecycle.rst +++ b/docs/decisions/0009-slot-naming-and-lifecycle.rst @@ -133,17 +133,20 @@ consistent names. For the purposes of versioning, a given slot's API contract is comprised of: -* Its location, visual or otherwise, in the Module -* The type (but not implementation!) of the content it is expected to wrap -* The specific set of properties, options, and operations it supports +* Its React props, with the notable exclusion of ``props.children`` (also known + as "default content"); -If one of the above changes for a particular slot in such a way that existing -widgets break or present undefined behavior, *and* if it still make sense to -use the same Identifier, the version string appended to its name will be -incremented by `1`. +* The location where it's rendered on the page; + +* The general type of content it's expected to wrap, though as mentioned above + this does not include the number or implementation of child elements: a given + slot's default content, including its presence or absence, is explicitly + *not* part of the slot's contract, and may change at any time. -Note: a given slot's default content is explicitly *not* part of its contract. -Changes to it do not result in a version bump. +If one of the above changes for a particular slot in such a way that existing +widgets can be reasonably expected to break or present otherwise undesireable +behavior, *and* if it still make sense to use the same Identifier, the version +string appended to its name will be incremented by `1`. 3. Deprecation process ---------------------- @@ -159,7 +162,7 @@ developer will take care to: least one Open edX release where it co-exists with the new version * Implement the new version of the slot in such a way that coexists with the - previous one with no detriment to either's functionality + previous one with no detriment to either one's functionality Consequences