1--- 2stage: none 3group: unassigned 4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 5--- 6 7# Renaming features 8 9Sometimes 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: 10 11- Complete, rename everything in the repository. 12 - Pros: does not increase code complexity. 13 - Cons: more work to execute, and higher risk of immediate bugs. 14- Façade, rename as little as possible; only the user-facing content like interfaces, 15 documentation, error messages, and so on. 16 - Pros: less work to execute. 17 - Cons: increases code complexity, creating higher risk of future bugs. 18 19## When to choose the façade approach 20 21The more of the following that are true, the more likely you should choose the façade approach: 22 23- You are not confident the new name is permanent. 24- The feature is susceptible to bugs (large, complex, needing refactor, etc). 25- The renaming is difficult to review (feature spans many lines, files, or repositories). 26- The renaming is disruptive in some way (database table renaming). 27 28## Consider a façade-first approach 29 30The façade approach is not necessarily a final step. It can (and possibly *should*) be treated as the first step, where later iterations accomplish the complete rename. 31