diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-01-29 09:08:49 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-01-29 09:08:49 +0000 |
commit | 46b10c0fc884400941c17e2777b242ac54d111e5 (patch) | |
tree | 184bc49764f03791610c8ae716c03e0100ed45f5 /doc | |
parent | 3358e1fdb8fe1e8f739024ee4f3d1071b296a010 (diff) | |
download | gitlab-ce-46b10c0fc884400941c17e2777b242ac54d111e5.tar.gz |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/development/README.md | 1 | ||||
-rw-r--r-- | doc/development/renaming_features.md | 24 |
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. |