Add latest changes from gitlab-org/gitlab@master

2 files changed, 25 insertions, 0 deletions

diff --git a/doc/development/README.md b/doc/development/README.md
index 5338db38430..84d4fb5519f 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -137,6 +137,7 @@ Complementary reads:
 - [Database helper modules](database_helpers.md)
 - [Code comments](code_comments.md)
 - [Creating enums](creating_enums.md)
+- [Renaming features](renaming_features.md)
 
 ### Case studies
 
diff --git a/doc/development/renaming_features.md b/doc/development/renaming_features.md
new file mode 100644
index 00000000000..ca204bd420e
--- /dev/null
+++ b/doc/development/renaming_features.md
@@ -0,0 +1,24 @@
+# Renaming features
+
+Sometimes the business asks to change the name of a feature. Broadly speaking, there are 2 approaches to that task. They basically trade between immediate effort and future complexity/bug risk:
+
+- Complete, rename everything in the repo.
+  - Pros: does not increase code complexity.
+  - Cons: more work to execute, and higher risk of immediate bugs.
+- Façade, rename as little as possible; only the user-facing content like interfaces,
+  documentation, error messages, etc.
+  - Pros: less work to execute.
+  - Cons: increases code complexity, creating higher risk of future bugs.
+
+## When to choose the façade approach
+
+The more of the following that are true, the more likely you should choose the façade approach:
+
+- You are not confident the new name is permanent.
+- The feature is susceptible to bugs (large, complex, needing refactor, etc).
+- The renaming will be difficult to review (feature spans many lines/files/repos).
+- The renaming will be disruptive in some way (database table renaming).
+
+## Consider a façade-first approach
+
+The façade approach is not necessarily a final step.  It can (and possibly *should*) be treated as the first step, where later iterations will accomplish the complete rename.