From 94b71aa22f06686443aeb734add00804e8ff6692 Mon Sep 17 00:00:00 2001 From: OracPrime Date: Mon, 16 Mar 2026 17:05:51 +0000 Subject: [PATCH 1/3] Encourage clean PRs when working on existing projects --- .../legacy/practices-to-remember/index.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/common-content/en/module/legacy/practices-to-remember/index.md b/common-content/en/module/legacy/practices-to-remember/index.md index b6f219c39..33059c7e7 100644 --- a/common-content/en/module/legacy/practices-to-remember/index.md +++ b/common-content/en/module/legacy/practices-to-remember/index.md @@ -19,12 +19,29 @@ Some of our standard development practices are _even more important_ when workin We should be _consistent_ with our formatting. We may not have any control over what decisions were made in the past. When we're writing brand new code in a new code, we can choose whether we use two spaces or four. But when we jump into an existing codebase, we should use whatever style it already has. If we send a PR fixing a small bug, and it changes every line in the file, it's really hard to see what changed, and what stayed the same. If we have two people joining a codebase, and one is reformatting every file they touch to use two spaces, and the other is reformatting every file they touch to use two spaces, there are going to be lots of spurious changes, and lots of merge conflicts.\ To approach this, we may need to: + * Disable our auto code formatters * Change the configuration of our auto code formatters (maybe by finding an existing configuration in the repo, or adding one) * Reformat the whole repo with a consistent configuration in one commit, and then keep it formatted. We should **never** include spurious reformatting changes in the same commit as real code changes. +### Clean PRs + +We should (almost!) always work from a clean copy of main. When you move from one task to the next, do not keep the changes from the previous task. Often in the real world your last PR will be merged to main before you branch for the new task, so you will have the changes included in the second task's PR, but they are not part of the branch, they are there as part of main. When doing these exercises (or in real world scenarios where your previous branch hasn't been merged) it is important to start from a clean checkout of main. You can do this before you start on the second task by using + +```plain +git reset --hard origin/main +``` + +If you realise (as often happens) too late, and you have your task2 changes as well as task1 changes, then if they are in different folders you can reset the task1 folder. Check the git history for the lsat commit to main and note the commit hash. Then do + +```plain +git restore --source=COMMIT_HASH --worktree task1folder +``` + +Whenever you commit, have a look at the changed files. Check they are only what you need for this task. + ### PR Descriptions PR descriptions are even more important when working with Legacy Code. We probably had to do a lot of learning to work out how something works, what was wrong, and how to fix out. The person reviewing our change may not know the codebase very well either. The more detail we can write in our PR descriptions, the more information the next person has when they need to investigate something (and the easier it will be for our reviewer to review our change). From 1246d2572a0e70f591bc3505f2c78c73065875db Mon Sep 17 00:00:00 2001 From: OracPrime Date: Mon, 16 Mar 2026 17:48:41 +0000 Subject: [PATCH 2/3] Including the clean route as well as the clean-up techniques --- .../module/legacy/practices-to-remember/index.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/common-content/en/module/legacy/practices-to-remember/index.md b/common-content/en/module/legacy/practices-to-remember/index.md index 33059c7e7..0393a844f 100644 --- a/common-content/en/module/legacy/practices-to-remember/index.md +++ b/common-content/en/module/legacy/practices-to-remember/index.md @@ -28,13 +28,23 @@ We should **never** include spurious reformatting changes in the same commit as ### Clean PRs -We should (almost!) always work from a clean copy of main. When you move from one task to the next, do not keep the changes from the previous task. Often in the real world your last PR will be merged to main before you branch for the new task, so you will have the changes included in the second task's PR, but they are not part of the branch, they are there as part of main. When doing these exercises (or in real world scenarios where your previous branch hasn't been merged) it is important to start from a clean checkout of main. You can do this before you start on the second task by using +We should (almost!) always work from a clean copy of main. When you move from one task to the next, do not keep the changes from the previous task. Often in the real world your last PR will be merged to main before you branch for the new task, so you will have the changes included in the second task's PR, but they are not part of the branch, they are there as part of main. When doing these exercises (or in real world scenarios where your previous branch hasn't been merged) it is important to start from a clean checkout of main. + +Ideally you'll think about this immediately after you submit the previous PR and before you make any changes. In which case the clean route is + +```plain +git switch -c new-branch main +``` + +which will remove your committed branch and create a new one based on main. + +If you've got random uncommitted changes in your local folder, they will not be removed by the above command. So before you do that command you can clean things up: ```plain git reset --hard origin/main ``` -If you realise (as often happens) too late, and you have your task2 changes as well as task1 changes, then if they are in different folders you can reset the task1 folder. Check the git history for the lsat commit to main and note the commit hash. Then do +If you realise (as often happens) too late, and are trying to clean up after you've created your new branch and you have your task2 changes as well as task1 changes, then if they are in different folders you can reset the task1 folder. Check the git history for the last commit to main and note the commit hash. Then do ```plain git restore --source=COMMIT_HASH --worktree task1folder From 003cf5762db1057baeceac473563c064efa297ad Mon Sep 17 00:00:00 2001 From: David Christensen Date: Wed, 18 Mar 2026 13:08:38 +0000 Subject: [PATCH 3/3] Update common-content/en/module/legacy/practices-to-remember/index.md Co-authored-by: Daniel Wagner-Hall --- common-content/en/module/legacy/practices-to-remember/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-content/en/module/legacy/practices-to-remember/index.md b/common-content/en/module/legacy/practices-to-remember/index.md index 0393a844f..e8cca5975 100644 --- a/common-content/en/module/legacy/practices-to-remember/index.md +++ b/common-content/en/module/legacy/practices-to-remember/index.md @@ -36,7 +36,7 @@ Ideally you'll think about this immediately after you submit the previous PR and git switch -c new-branch main ``` -which will remove your committed branch and create a new one based on main. +which will create a new one based on main, and switch to it. If you've got random uncommitted changes in your local folder, they will not be removed by the above command. So before you do that command you can clean things up: