From 62dbfdb7847e6a1a2d66e10160e77cafc1897cc4 Mon Sep 17 00:00:00 2001 From: wxiaoguang Date: Mon, 13 Feb 2023 01:05:09 +0800 Subject: [PATCH 1/2] doc --- .../guidelines-refactoring.en-us.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/content/doc/developers/guidelines-refactoring.en-us.md 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 0000000000000..f51f77a78e0d6 --- /dev/null +++ b/docs/content/doc/developers/guidelines-refactoring.en-us.md @@ -0,0 +1,52 @@ +--- +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. From 2149eeb92feafd49a8d82d07c004866ddd1bb0a5 Mon Sep 17 00:00:00 2001 From: wxiaoguang Date: Sun, 19 Feb 2023 20:57:11 +0800 Subject: [PATCH 2/2] Update docs/content/doc/developers/guidelines-refactoring.en-us.md --- docs/content/doc/developers/guidelines-refactoring.en-us.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/content/doc/developers/guidelines-refactoring.en-us.md b/docs/content/doc/developers/guidelines-refactoring.en-us.md index f51f77a78e0d6..2d607720dcb80 100644 --- a/docs/content/doc/developers/guidelines-refactoring.en-us.md +++ b/docs/content/doc/developers/guidelines-refactoring.en-us.md @@ -28,7 +28,6 @@ To make the codebase more maintainable and make Gitea better, developers should 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.