Clarifications in the reviewing exercise

04_documentation/reviewing_exercise.md

@@ -4,11 +4,16 @@ Let us get familiar with code review tools and practices.
 
 Deadline: **December 17, 2025, 9:00**
 
-**Note:** This is the first time that we have this exercise. Feedback and suggestions is very welcome - [open an issue](https://github.com/Simulation-Software-Engineering/Lecture-Material/issues).
+**Note:** In this exercise, we use GenAI tools, which evolve rapidly. Feedback and suggestions are very welcome - [open an issue](https://github.com/Simulation-Software-Engineering/Lecture-Material/issues).
+
+## Prerequisites
+
+- Login to the [Responsible AI](https://rai.uni-stuttgart.de)
+- Get access to [GitHub Education](https://github.com/education/students). After verification, according to GitHub, it might take up to 72h for the features to be available. If for any reason you cannot or do not want sign up for it, you can try any other code reviewing tool you might have available (e.g., Copilot in VSCode). For the grading, we do not need to see the output of the tool, but only your comments on your experience with it.
 
 ## Overview
 
-In this exercise, you will work responsibly with AI tools to write and review code.
+In this exercise, you will work responsibly with AI tools to write code, review it as it if was a colleague's code, and use more AI tools for an additional review.
 More specifically, you will:
 
 1. use [Responsible AI](https://rai.uni-stuttgart.de) to write a simulation program,
@@ -19,8 +24,6 @@ More specifically, you will:
 
 In the end, you will need to open an issue in the [exercise repository](https://github.com/Simulation-Software-Engineering/reviewing-exercise) with name `[username] Reviewing exercise submission`.
 
-**Update, Dec 10:** GitHub copilot is available as part of GitHub Pro, which you can get access to as a student via [GitHub Education](https://github.com/education/students). After verification, according to GitHub, it might take up to 72h for the features to be available. If for any reason you cannot or do not want sign up for it, you can try any other code reviewing tool you might have available (e.g., Copilot in VSCode). For the grading, we do not need to see the output of the tool, but only your comments on your experience with it. If you have no access to AI reviewing tools, declare that and put more emphasis on the comparison with your challenge project.
-
 ## Generate code
 
 Generating code can be very useful to kick-start a project or to fill rather clear code parts (such as basic tests or documentation).
@@ -33,14 +36,16 @@ You remain in control and responsible for your projects.
 Now that we have set some guidelines, let's see the strengths in action:
 
 1. Login to the [Responsible AI](https://rai.uni-stuttgart.de) provided by the University of Stuttgart.
-   - Due to a bug (as of December 2025), start by saying "Hi" before proceeding with actual prompts. Apparently, bots also have psychological needs. :)
+    - If the first prompt does not work, start by saying "Hi" before proceeding with actual prompts. Apparently, bots also have psychological needs. :)
 2. In your own words, ask the tool to generate code for solving a heat equation, in a programming language you understand (e.g., Python).
    Ask it to take parameters from a configuration file and write results to an output file.
    Ask for some documentation, tests, or anything else you would like to see in such a code.
 3. Create a repository on GitHub (under your namespace) and initialize it with a `README.md` file.
 4. Add the files that RAI created to the repository, in a branch called `feature`. In your commit message, clearly disclose the tool. For example:
 
    ```text
+    (... usual commit message ...)
+
     I acknowledge the use of RAI (https://rai.uni-stuttgart.de/) to implement the entirety of this code.
 
     Prompts:
@@ -50,7 +55,7 @@ Now that we have set some guidelines, let's see the strengths in action:
 
    The more details you add, the better.
 
-5. Open a merge request from the branch `feature` to the `main` branch.
+5. Open a merge request from the branch `feature` to the `main` branch. Make sure to give a good PR title and description, as if you were contributing this code, and focusing on what this PR adds; not only the AI generation.
 
 ## Review the code
 
@@ -72,9 +77,9 @@ Start an issue in the [exercise repository](https://github.com/Simulation-Softwa
 
 GitHub Copilot can automatically review a pull request. Add it as a reviewer and wait for it to submit a review.
 
-Carefully go through the review. Apply comments you agree with, comment on the points you don't agree with.
+Carefully go through the review. Comment on the suggestions, apply suggestions you agree with, comment on the points you don't agree with.
 
-Optional: Give [custom instructions to Copilot](https://docs.github.com/en/copilot/tutorials/customization-library/custom-instructions) (such as [code reviewer](https://docs.github.com/en/copilot/tutorials/customization-library/custom-instructions/code-reviewer)).
+Optional: Give [custom instructions to Copilot](https://docs.github.com/en/copilot/tutorials/customization-library/custom-instructions) (such as [code reviewer](https://docs.github.com/en/copilot/tutorials/customization-library/custom-instructions/code-reviewer)). You could directly ask Copilot (agent) to apply specific suggestions in the same branch or in separate PRs.
 
 In the issue you just opened, edit the description and comment: