diff options
| -rw-r--r-- | docs/content/doc/developers/guidelines-refactoring.en-us.md | 51 |
1 files changed, 51 insertions, 0 deletions
diff --git a/docs/content/doc/developers/guidelines-refactoring.en-us.md b/docs/content/doc/developers/guidelines-refactoring.en-us.md new file mode 100644 index 0000000000..2d607720dc --- /dev/null +++ b/docs/content/doc/developers/guidelines-refactoring.en-us.md @@ -0,0 +1,51 @@ +--- +date: "2023-02-14T00:00:00+00:00" +title: "Guidelines for Refactoring" +slug: "guidelines-refactoring" +weight: 20 +toc: false +draft: false +menu: +sidebar: +parent: "developers" +name: "Guidelines for Refactoring" +weight: 20 +identifier: "guidelines-refactoring" +--- + +# Guidelines for Refactoring + +**Table of Contents** + +{{< toc >}} + +## Background + +Since the first line of code was written at Feb 12, 2014, Gitea has grown to be a large project. +As a result, the codebase has become larger and larger. The larger the codebase is, the more difficult it is to maintain. +A lot of outdated mechanisms exist, a lot of frameworks are mixed together, some legacy code might cause bugs and block new features. +To make the codebase more maintainable and make Gitea better, developers should keep in mind to use modern mechanisms to refactor the old code. + +This document is a collection of guidelines for refactoring the codebase. + +## Refactoring Suggestions + +* Design more about the future, but not only resolve the current problem. +* Reduce ambiguity, reduce conflicts, improve maintainability. +* Describe the refactoring, for example: + * Why the refactoring is needed. + * How the legacy problems would be solved. + * What's the Pros/Cons of the refactoring. +* Only do necessary changes, keep the old logic as much as possible. +* Introduce some intermediate steps to make the refactoring easier to review, a complete refactoring plan could be done in several PRs. +* If there is any divergence, the TOC(Technical Oversight Committee) should be involved to help to make decisions. +* Add necessary tests to make sure the refactoring is correct. +* Non-bug refactoring is preferred to be done at the beginning of a milestone, it would be easier to find problems before the release. + +## Reviewing & Merging Suggestions + +* A refactoring PR shouldn't be kept open for a long time (usually 7 days), it should be reviewed as soon as possible. +* A refactoring PR should be merged as soon as possible, it should not be blocked by other PRs. +* If there is no objection from TOC, a refactoring PR could be merged after 7 days with one core member's approval (not the author). +* Tolerate some dirty/hacky intermediate steps if the final result is good. +* Tolerate some regression bugs if the refactoring is necessary, fix bugs as soon as possible. |