cjyuan · cjyuan · Oct 1, 2025
diff --git a/org-cyf-guides/content/trainee-pr-guide/_index.md b/org-cyf-guides/content/trainee-pr-guide/_index.md
@@ -0,0 +1,26 @@
++++
+title="Trainee Pull Request Guide"
+description="What trainees should know about PR in CYF course"
+emoji="📝"
+menu=["everyone"]
++++
+
+### What is a Pull Request (PR)?
+
+A **pull request**, or **PR**, is a way to share your code for review.
+In professional projects, PRs are used to suggest changes and then merge them into the main project.
+
+At CodeYourFuture, we use PRs mainly as a way for you to submit your work for review and feedback.
+Think of it like handing in an assignment - the PR is the place where you "submit" your code so 
+mentors and teammates can:
+- ✅ See what you changed (new code, fixes, or features)
+- 💬 Discuss the changes (comments, suggestions, or questions)
+- 👍 Review and provide feedback (approve or request improvements)
+
+For most coursework, merging will not happen. You will update your code based on feedback, learn 
+from the process, and keep practicing.
+
+### How do you work with a PR? 
+
+To get the most out of a PR, follow these steps to get 
+clear feedback, show your progress, and learn more effectively.
diff --git a/org-cyf-guides/content/trainee-pr-guide/keeping-branch-clean/index.md b/org-cyf-guides/content/trainee-pr-guide/keeping-branch-clean/index.md
@@ -0,0 +1,42 @@
++++
+title = "Keeping Branches and Code Clean"
+description="How to keep your branches and code clean and professional"
+emoji = "✨"
+weight = 1
++++
+
+### Keeping a branch clean
+
+A **clean branch** contains only the work you want to share, nothing more.
+It makes your PR easier to review.
+
+To keep your exercise branch clean:
+
+1. **Create your branch from `main`**.
+
+2. **Keep `main` clean and updated**.
+    - _Clean_ -> no exercise changes should be committed to `main`.
+    - _Updated_ -> regularly pull changes from the upstream repo.
+
+3. **Make only related changes**.
+    - Add or modify only the files in the folder belonging to the exercise.
+
+### Keeping code clean
+
+Clean code makes it easier for you, your teammates, and your reviewers to understand and
+work with.
+
+Refer to the [Code Style Guide](https://programming.codeyourfuture.io/guides/reviewing/style-guide/)
+to learn how to keep your code professional.
+
+### Get a second opinion from AI tools
+
+Before submitting a PR, you can use AI tools to review your code, documentation, or explanations.
+
+AI can help you:
+- Spot typos, formatting issues, or unclear comments.
+- Suggest possible improvements to your code or approach.
+- Highlight missing edge cases or potential problems.
+
+Think of AI as a second pair of eyes -- helpful for polishing your work.  
+And don’t worry: using AI is **not cheating**. You can accept AI suggestions, but only if you understand them well enough to explain the change. Once you can do that, the learning truly becomes yours.
diff --git a/org-cyf-guides/content/trainee-pr-guide/opening-a-pr/index.md b/org-cyf-guides/content/trainee-pr-guide/opening-a-pr/index.md
@@ -0,0 +1,76 @@
++++
+title = "Opening PR"
+description="How to submit your work the right way"
+emoji = "🔀"
+weight = 2
++++
+
+### Selecting source and target branches
+- **Source branch**: Your branch
+- **Target branch**: The branch you want to compare to -- normally CodeYourFuture's `main`.
+
+### PR Title
+A consistent title format makes pull requests easier to track, search, and review.
+
+{{<note type="note" title="In CYF Course">}}
+In CYF courses, you can typically find the title format in the PR template.
+
+For example,
+```
+  Region | Cohort | FirstName LastName | Sprint | Assignment Title
+```  
+means the title should have 5 components separated by a vertical bar character (`|`)
+
+- **`Region`**: One of 
+  - `Cape Town`, `South Africa`, `ZA`
+  - `Glasgow`, `Scotland`
+  - `London`
+  - `North West`, `NW`, `Manchester`
+  - `Sheffield`
+  - `West Midlands`, `WM`, `Birminghams`
+- **`Cohort`**: In the form `year`-`course name`-`cohort starting month` (e.g., `25-ITP-Sep`)
+- **`FirstName LastName`**: 🙄
+- **`Sprint`**: `Sprint 1`, `Sprint 2`, ...
+- **`Assignment Title`**: Project or exercise name, or the **assignment title** specified 
+  in the backlog.
+
+{{</note>}}
+
+### PR Description
+
+The **PR description** is where you explain what your changes are and why you made them.
+It helps reviewers quickly understand the context without having to read all the code.
+
+The PR template in CYF courses typically contain the following sections:
+
+#### 1. Self-checklist
+
+The self-checklist helps you remember important steps, shows reviewers you've prepared your work, 
+and speeds up the review process - while building good professional habits for real-world projects.
+
+You should only tick items you've truly completed, check every box before submitting, 
+and treat the checklist as both your responsibility and a learning tool - ask for help if you're 
+unsure.
+
+{{<note type="note" title="In CYF Course">}}
+Complete every item in the checklist, and mark each one as done by changing `- [ ]` to `- [x]` 
+in Markdown.
+{{</note>}}
+
+#### 2. Changelist
+
+The Changelist section is a short, bullet-point summary of the key changes in your PR, 
+helping reviewers quickly understand what you did and why.
+
+{{<note type="note" title="In CYF Course">}}
+Replace the placeholder text `Briefly explain your PR` by a brief description of your changes.
+{{</note>}}
+
+#### 3. Questions
+
+The Questions section lets you highlight parts of your work you’re unsure about, 
+so reviewers can give you targeted feedback and help you learn.
+
+{{<note type="note" title="In CYF Course">}}
+Replace the placeholder text by your questions, or delete the section if you don't have any.
+{{</note>}}
diff --git a/org-cyf-guides/content/trainee-pr-guide/responding-to-comments/index.md b/org-cyf-guides/content/trainee-pr-guide/responding-to-comments/index.md
@@ -0,0 +1,34 @@
++++
+title = "Addressing Comments"
+description="How to respond to feedback and improve your code"
+emoji = "💬"
+weight = 4
++++
+
+Responding to PR feedback is like a conversation: **listen**, **reply thoughtfully**, and 
+**show that you acted on feedback**.
+
+1. **Be respectful and collaborative**
+    - Treat comments as opportunities to learn, not criticism.
+    - Even if you disagree, respond politely and explain your reasoning.
+
+2. **Acknowledge feedback**
+    - If you agree -> say _"Good point, I'll fix it."_
+    - If you don't fully agree -> say _"I see your point. Here's why I approached it this way ..."_
+    - **Don't ignore comments** -- silence can feel dismissive.
+
+3. **Make changes, then confirm**
+    - After addressing a comment, let the reviewer know (e.g., _"I've updated the variable name 
+      as suggested."_).
+    - This shows you're actively engaging in the review.
+
+4. **Ask questions if unclear**
+    - If you don't understand a suggestion, ask for clarification.
+    - Example: _"Could you explain what you mean by simplifying this function?"_
+
+
+{{<note type="tips" title="Markdown">}}
+
+Text in the comment boxes are formatted in [Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) syntax. 
+
+{{</note>}}
diff --git a/org-cyf-guides/content/trainee-pr-guide/using-labels/index.md b/org-cyf-guides/content/trainee-pr-guide/using-labels/index.md
@@ -0,0 +1,26 @@
++++
+title = "Using Labels"
+description="How to make your PR easier to understand and track"
+emoji = "🏷️"
+weight = 3
++++
+
+In CodeYourFuture's courses, we use PRs a little differently.
+For coursework, merging is not required. Instead of relying on "approve and merge,"
+we use labels to show the state of a PR.
+
+Here is a summary of labels to be added to a PR during a review cycle.
+
+- `Needs review` - Added by a trainee when a PR is first created, or when all reviewer feedback 
+  has been addressed.
+  - Replaces `Reviewed` (if present).
+
+- `Review in progress` - Added by a mentor to show that they are currently reviewing the PR.
+
+- `Reviewed` - Added by a mentor once the PR has been reviewed and the trainee can start working 
+  on feedback.
+  - Replaces `Needs review` and `Review in progress`.
+
+- `Complete` - Added by a mentor when the PR has been approved.
+
+
diff --git a/org-cyf-itp/package.json b/org-cyf-itp/package.json
@@ -7,7 +7,8 @@
     "test": "echo \"Error: no test specified\" && exit 1",
     "start:dev": "dotenv -e ../.env -- hugo server --environment development",
     "build:dev": "hugo mod vendor && dotenv -e ../.env  -- hugo --environment development",
-    "build:audit": "HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true hugo mod vendor && dotenv -e ../.env  -- hugo --environment production && grep -inorE '<\\!-- raw HTML omitted -->|ZgotmplZ|\\[i18n\\]|\\(<nil>\\)|(&lt;nil&gt;)|hahahugo' public/"
+    "build:audit": "HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true hugo mod vendor && dotenv -e ../.env  -- hugo --environment production && grep -inorE '<\\!-- raw HTML omitted -->|ZgotmplZ|\\[i18n\\]|\\(<nil>\\)|(&lt;nil&gt;)|hahahugo' public/",
+    "generate:dev": "dotenv -e ../.env -- hugo --environment development --destination ../../itp-curriculum-preview"
   },
   "keywords": [],
   "author": "",