Merge branch 'ps-fix-header-ordering-in-ee-features-docs' into 'master'

Fix header ordering in ee_features

See merge request gitlab-org/gitlab!81852

doc/development/ee_features.md

@@ -444,6 +444,69 @@ resolve when you add the indentation to the equation.
 EE-specific views should be placed in `ee/app/views/`, using extra
 sub-directories if appropriate.
 
+#### Using `render_if_exists`
+
+Instead of using regular `render`, we should use `render_if_exists`, which
+doesn't render anything if it cannot find the specific partial. We use this
+so that we could put `render_if_exists` in CE, keeping code the same between
+CE and EE.
+
+The advantages of this:
+
+- Very clear hints about where we're extending EE views while reading CE code.
+
+The disadvantage of this:
+
+- If we have typos in the partial name, it would be silently ignored.
+
+##### Caveats
+
+The `render_if_exists` view path argument must be relative to `app/views/` and `ee/app/views`.
+Resolving an EE template path that is relative to the CE view path doesn't work.
+
+```haml
+- # app/views/projects/index.html.haml
+
+= render_if_exists 'button' # Will not render `ee/app/views/projects/_button` and will quietly fail
+= render_if_exists 'projects/button' # Will render `ee/app/views/projects/_button`
+```
+
+#### Using `render_ce`
+
+For `render` and `render_if_exists`, they search for the EE partial first,
+and then CE partial. They would only render a particular partial, not all
+partials with the same name. We could take the advantage of this, so that
+the same partial path (for example, `shared/issuable/form/default_templates`) could
+be referring to the CE partial in CE (that is,
+`app/views/shared/issuable/form/_default_templates.html.haml`), while EE
+partial in EE (that is,
+`ee/app/views/shared/issuable/form/_default_templates.html.haml`). This way,
+we could show different things between CE and EE.
+
+However sometimes we would also want to reuse the CE partial in EE partial
+because we might just want to add something to the existing CE partial. We
+could workaround this by adding another partial with a different name, but it
+would be tedious to do so.
+
+In this case, we could as well just use `render_ce` which would ignore any EE
+partials. One example would be
+`ee/app/views/shared/issuable/form/_default_templates.html.haml`:
+
+```haml
+- if @project.feature_available?(:issuable_default_templates)
+  = render_ce 'shared/issuable/form/default_templates'
+- elsif show_promotions?
+  = render 'shared/promotions/promote_issue_templates'
+```
+
+In the above example, we can't use
+`render 'shared/issuable/form/default_templates'` because it would find the
+same EE partial, causing infinite recursion. Instead, we could use `render_ce`
+so it ignores any partials in `ee/` and then it would render the CE partial
+(that is, `app/views/shared/issuable/form/_default_templates.html.haml`)
+for the same path (that is, `shared/issuable/form/default_templates`). This way
+we could easily wrap around the CE partial.
+
 ### Code in `lib/gitlab/background_migration/`
 
 When you create EE-only background migrations, you have to plan for users that
@@ -525,69 +588,6 @@ module EE
 end
 ```
 
-#### Using `render_if_exists`
-
-Instead of using regular `render`, we should use `render_if_exists`, which
-doesn't render anything if it cannot find the specific partial. We use this
-so that we could put `render_if_exists` in CE, keeping code the same between
-CE and EE.
-
-The advantages of this:
-
-- Very clear hints about where we're extending EE views while reading CE code.
-
-The disadvantage of this:
-
-- If we have typos in the partial name, it would be silently ignored.
-
-##### Caveats
-
-The `render_if_exists` view path argument must be relative to `app/views/` and `ee/app/views`.
-Resolving an EE template path that is relative to the CE view path doesn't work.
-
-```haml
-- # app/views/projects/index.html.haml
-
-= render_if_exists 'button' # Will not render `ee/app/views/projects/_button` and will quietly fail
-= render_if_exists 'projects/button' # Will render `ee/app/views/projects/_button`
-```
-
-#### Using `render_ce`
-
-For `render` and `render_if_exists`, they search for the EE partial first,
-and then CE partial. They would only render a particular partial, not all
-partials with the same name. We could take the advantage of this, so that
-the same partial path (for example, `shared/issuable/form/default_templates`) could
-be referring to the CE partial in CE (that is,
-`app/views/shared/issuable/form/_default_templates.html.haml`), while EE
-partial in EE (that is,
-`ee/app/views/shared/issuable/form/_default_templates.html.haml`). This way,
-we could show different things between CE and EE.
-
-However sometimes we would also want to reuse the CE partial in EE partial
-because we might just want to add something to the existing CE partial. We
-could workaround this by adding another partial with a different name, but it
-would be tedious to do so.
-
-In this case, we could as well just use `render_ce` which would ignore any EE
-partials. One example would be
-`ee/app/views/shared/issuable/form/_default_templates.html.haml`:
-
-```haml
-- if @project.feature_available?(:issuable_default_templates)
-  = render_ce 'shared/issuable/form/default_templates'
-- elsif show_promotions?
-  = render 'shared/promotions/promote_issue_templates'
-```
-
-In the above example, we can't use
-`render 'shared/issuable/form/default_templates'` because it would find the
-same EE partial, causing infinite recursion. Instead, we could use `render_ce`
-so it ignores any partials in `ee/` and then it would render the CE partial
-(that is, `app/views/shared/issuable/form/_default_templates.html.haml`)
-for the same path (that is, `shared/issuable/form/default_templates`). This way
-we could easily wrap around the CE partial.
-
 ### Code in `lib/`
 
 Place EE-specific logic in the top-level `EE` module namespace. Namespace the