admin/customization: No need to be a developer for custom branding (#427)

Preview: https://forgejo.codeberg.page/@docs_pull_427/docs/next/admin/customization/

---

The previous version of this document insinuated that you need to be
familiar with Forgejo's source code and compile Forgejo from source
for custom branding changes. As of the most recent Forgejo version,
this is not necessarily true, as custom files can be served from
the CustomPath.

Administrators that were not developers therefore dismissed the
other guide and its contents without reading this, and I was one
of them. I thought it would make sense for this file to provide
information on where to put a custom logo. This change does not
fix it (this will be done later), but it will reduce the confusion
for now.

This warning confused me personally and other Forgejo users, as I
had one person tell me IRL that they thought that it was not possible
to serve a custom logo.

Reviewed-on: https://codeberg.org/forgejo/docs/pulls/427
Reviewed-by: Earl Warren <earl-warren@noreply.codeberg.org>
Co-authored-by: Panagiotis "Ivory" Vasilopoulos <git@n0toose.net>
Co-committed-by: Panagiotis "Ivory" Vasilopoulos <git@n0toose.net>

docs/admin/customization.md

@@ -5,13 +5,33 @@ license: 'CC-BY-SA-4.0'
 
 Forgejo currently has limited capabilities for customizing the user interface.
 
-Some settings are provided to customize the look and feel of the Forgejo user interface, such as the default theme or the description that shows on the home page. See a complete list of those settings in the config cheat sheet:
+## Configurations and UI settings
+
+Some settings are provided to customize the look and feel of the Forgejo user interface.
+
+This includes the default theme, the name of your Forgejo instance, as well as the description that appears in Forgejo's homepage. A complete list of those settings can be found in the config cheat sheet:
 
 - In the [UI section](../config-cheat-sheet/#ui-ui) and below.
 - The `APP_NAME` setting in the [Overall section](../config-cheat-sheet/#overall-default)
 
 They are documented and supported to be backward compatible between versions.
 
-It is also possible to customize Forgejo by recompiling from the sources and changing the files. Or by extracting and modifying the relevant files with the `forgejo embedded extract` CLI. In both cases an intimate knowledge of the underlying codebase is necessary to figure out what files should be modified to achieve the desired result. They are considered an internal detail: non backward compatible changes will be introduced without warning in the release notes and they will not be documented.
+## Serving custom resources, logos and pages
 
-See also the [developer section on interface customization](../../developer/customization/) for more information.
+### A word of warning (Here be dragons!)
+
+Setting a custom logo for your instance, serving custom public files or modifying pages shown by Forgejo (such as the homepage) is possible. However, they impose an additional maintenance burden on administrators and, most importantly, **are unsupported**.
+
+**Unsupported** means that future updates **are likely to break** your changes **without any warning**.
+
+#### Templates
+
+The most dangerous types of modifications are the ones concerning **template files** (`.tmpl`) served by Forgejo, as Forgejo issues backward incompatible updates to its templates very regularly.
+
+Before deploying your changes to production or upgrading a modified Forgejo instance, we urge that you test your custom modifications in a testing environment first.
+
+### Instructions
+
+For the reasons mentioned above, the instructions on performing such tasks can be found in the [developer section on interface customization](../../developer/customization/).
+
+At this stage, it is also worth mentioning that it is possible to customize Forgejo by [modifying its source code and compiling the changes](../../developer/from-source), or by extracting and modifying the files of your choice using the command `forgejo embedded extract`. However, these methods are, for the same reasons as mentioned above, also **unsupported**.

docs/developer/customization.md

@@ -64,7 +64,11 @@ which can be modified by placing replacements below the `$FORGEJO_CUSTOM/templat
 To obtain any embedded file (including templates), the `forgejo embedded` CLI can be used. Alternatively, they can be found in the [`templates`](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/templates) directory of Forgejo source.
 
 Be aware that any statement contained inside `{{` and `}}` are Forgejo's template syntax and
-shouldn't be touched without fully understanding these components.
+should **not** be touched without fully understanding these components.
+
+Forgejo regularly makes backward incompatible changes to its own templates, which makes templates **very likely to break when upgrading Forgejo**.
+
+Before deploying your changes to production or upgrading a modified Forgejo instance, we urge that you test your custom modifications in a testing environment first.
 
 ### Customizing startpage / homepage