diff --git a/org-cyf-guides/content/trainee-pr-guide/_index.md b/org-cyf-guides/content/trainee-pr-guide/_index.md new file mode 100644 index 000000000..e9bb8a9f9 --- /dev/null +++ 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 new file mode 100644 index 000000000..494aeef83 --- /dev/null +++ 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 new file mode 100644 index 000000000..d6aeb64a8 --- /dev/null +++ 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. + +{{}} +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. + +{{}} + +### 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. + +{{}} +Complete every item in the checklist, and mark each one as done by changing `- [ ]` to `- [x]` +in Markdown. +{{}} + +#### 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. + +{{}} +Replace the placeholder text `Briefly explain your PR` by a brief description of your changes. +{{}} + +#### 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. + +{{}} +Replace the placeholder text by your questions, or delete the section if you don't have any. +{{}} 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 new file mode 100644 index 000000000..5ce0c8105 --- /dev/null +++ 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?"_ + + +{{}} + +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. + +{{}} 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 new file mode 100644 index 000000000..25df3c9bb --- /dev/null +++ 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 index f61d14ae6..04be2b8f0 100644 --- 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>)|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>)|hahahugo' public/", + "generate:dev": "dotenv -e ../.env -- hugo --environment development --destination ../../itp-curriculum-preview" }, "keywords": [], "author": "",