Add basic hands-on

Author: woojiahao

docs/architecture/hands-on-structure.md

@@ -0,0 +1,4 @@
+---
+title: Hands-on Structure
+parent: Architecture
+---

docs/contributing/exercise.md

@@ -12,7 +12,7 @@ nav_order: 2
 If you are proposing a new exercise (i.e., not implementing an [already approved exercise proposal](https://github.com/git-mastery/exercises/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22exercise%20discussion%22%20label%3A%22help%20wanted%22)) make sure that you have done the following:
 
 - [ ] Create an [exercise discussion](https://github.com/git-mastery/exercises/issues/new?template=exercise_discussion.yaml)
-- [ ] Obtained approval on the exercise
+- [ ] Obtain approval on the exercise
 - [ ] File a [remote repository request](https://github.com/git-mastery/exercises/issues/new?template=request_exercise_repository.yaml)
 
 ## Create a new exercise

docs/contributing/hands-on.md

@@ -4,190 +4,59 @@ parent: Contributing
 nav_order: 1
 ---
 
-# Contributing an exercise
+1. TOC
+{:toc}
 
 ## Before contributing
 
-If you are proposing a new exercise (i.e., not implementing an [already approved exercise proposal](https://github.com/git-mastery/exercises/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22exercise%20discussion%22%20label%3A%22help%20wanted%22)) make sure that you have done the following:
-- [ ] Create an [exercise discussion](https://github.com/git-mastery/exercises/issues/new?template=exercise_discussion.yaml)
-- [ ] Obtained approval on the exercise
-- [ ] File a [remote repository request](https://github.com/git-mastery/exercises/issues/new?template=request_exercise_repository.yaml)
-
-## Prerequisites
-
-- Bash environment
-- Python 3.13
-- Github CLI [installed and authenticated](https://github.com/cli/cli#installation) for testing the download script
-
-## Setup
-
-1. Fork this repository
-2. Clone the fork
-
-    ```bash
-    git clone https://github.com/<username>/exercises
-    ```
-
-3. Setup a virtual environment
-
-    ```bash
-    python -m venv venv
-    ```
-
-4. Activate the virtual environment
-
-    ```bash
-    source venv/bin/activate
-    ```
-
-    If you are using Windows, you should run the following instead: 
-
-    ```bash
-    source venv/Scripts/activate
-    ```
+If you are proposing a new hands-on (i.e., not implementing an [already approved hands-on proposal](https://github.com/git-mastery/exercises/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22hands-on%20discussion%22%20label%3A%22help%20wanted%22)) make sure that you have done the following:
 
-5. Install all dependencies
-
-    ```bash
-    pip install -r requirements.txt
-    ```
+- [ ] Create an [hands-on discussion](https://github.com/git-mastery/exercises/issues/new?template=hands_on_discussion.yaml)
+- [ ] Obtain approval on the hands-on
+- [ ] File a [remote repository request](https://github.com/git-mastery/exercises/issues/new?template=request_exercise_repository.yaml)
 
-## Create a new exercise
+## Create a new hands-on
 
 Use the provided `new.sh` script to generate the scaffolding for a new exercise:
 
 ```bash
 ./new.sh
 ```
 
-This script will prompt you for:
-
-1. The name of the exercise -- likely to be specified in the corresponding exercise discussion
-2. The exercise tags (split by space) -- likely to be specified in the corresponding exercise discussion
-3. The exercise configuration (read the [`.gitmastery-exercise.json` configuration](#gitmastery-exercisejson-configuration) section for more info on this)
-
-> [!TIP]
-> You should use kebab case for the exercise name.
-
-It then generates the following directory structure:
-
-```text
-<exercise name>
-├── .gitmastery-exercise.json
-├── README.md
-├── __init__.py
-├── download.py
-├── res
-│   └── ...
-├── tests
-│   ├── specs
-│   │   └── base.yml
-│   └── test_verify.py
-└── verify.py
-```
+The script will first prompt if you want to create a hands-on or exercise:
 
-- `.gitmastery-exercise.json`: contains the exercise configuration
-- `README.md`: contains the instructions for the exercise for the students to attempt
-- `download.py`: contains the download instructions to setup the student's exercise
-- `verify.py`: contains the verification script for the exercise attempt
-- `res/`: contains resources that are available to students (see this section about [types of resources](#types-of-resources))
-- `tests/specs/`: contains specification files written using [`repo-smith`](https://github.com/git-mastery/git-autograder)
-- `tests/test_verify.py`: contains unit tests for verification script
+Enter `hands-on` or `h` to create a new hands-on.
 
-### `.gitmastery-exercise.json` configuration
+Then, the script will prompt you for:
 
-The `.gitmastery-exercise.json` is used to tell the [Git-Mastery app](https://git-mastery.github.io/app) how to setup the student's exercise.
+1. The name of the hands-on -- likely to be specified in the corresponding hands-on discussion (you should be using kebab case for the hands-on name)
+2. Does the exercise require Git?
+3. Does the exercise require Github?
 
-The `new.sh` script should have already generated one for you, but you may change your mind with the configuration and modify the file directly:
+{: .reference }
 
-- `exercise_name`: raw exercise name that will be indexed; recommended to use [kebab case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case)
-- `tags`: used during indexing on the [exercise directory](https://git-mastery.github.io/exercises)
-- `requires_git`: performs a check to ensure that Git is installed and the user has already configured their `user.name` and `user.email`
-- `requires_github`: performs a check to ensure that Github CLI is installed and the user has already authenticated themselves
-- `base_files`: specifies the files from `res/` to be downloaded into the exercise root; typically used for the `answers.txt` (more about grading types [here]())
-- `exercise_repo`: controls the sub-folder that is generated; this is where students work on the exercise
-  - `repo_type`: `local` or `remote`; if `remote`, then the sub-folder is generated from a remote repository
-  - `repo_name`: name of the sub-folder; required for both `repo_type`
-  - `init`: determines if `git init` is run for the sub-folder; required only for `local`
-  - `create_fork`: determines if a fork is created on the user's Github account; required only for `remote`
-  - `repo_title`: name of the remote repository to fork + clone; required only for `remote`
+Refer to the [hands-on structure document](/developers/docs/architecture/hands-on-structure) for more information about the folder structure generated.
 
-## Designing download process
+## Download setup
 
 The `download.py` contains the instructions to setup the local repository.
 
-This is the sequence in which the Git-Mastery app downloads an exercise for a student:
-
-```mermaid
-flowchart
-a[Download exercise] --> b[Create exercise folder]
-b --> c[Download base files to exercise root]
-c --> d[Check Git if toggled]
-d --> e[Check Github if toggled]
-e -- local --> f[Create local repo folder with repo_name]
-e -- remote --> g[Fork repository if toggled]
-g --> h[Clone repository with repo_name]
-f --> i[Download resources]
-h --> i
-i --> j[Create initial commit if init toggled]
-j --> k[Execute download function]
-```
-
-As a result, the `download` function is the last step after you have already setup the folder structures and downloaded the base files and resources.
-
-The default download script comes with a helper function to `run_command` to run local commands.
-
-> [!NOTE]
-> You should be using OS-agnostic commands in the download script
-
-The initial download script also includes a command to attach a tag as the "start tag". This is only useful if you want to iterate through the user's commits in your verification script. Otherwise, this can be removed.
-
-Refer to existing `download.py` for reference on how to setup the download script.
-
-### What students see
-
-When a student downloads an exercise, they will see the following folder structure:
+{: .reference }
 
-```text
-<exercise name>
-├── .gitmastery-exercise.json
-├── README.md
-└── <sub folder name>
-    ├── .git
-    └── ...
-```
-
-The root of the exercise will contain the `README.md` and `.gitmastery-exercise.json` configured from your template.
-
-It also contains the sub-folder configured in `.gitmastery-exercise.json`, which is where students will attempt the exercise.
+For more information about how Git-Mastery downloads exercises, refer to the [Download Workflow](/developers/docs/architecture/download-workflow)
 
-### Types of resources
+The default download script comes with a helper function to `run_command` to run local command, and a command to attach a tag as the "start tag". This is only useful if you want to iterate through the user's commits in your verification script. Otherwise, this can be removed.
 
-There are two distinct types of resources:
+These are some references for download setups for other exercises:
 
-1. Base files: configured through the `base_files` property in `.gitmastery-exercise.json` in your template; files located in `res/` are downloaded to the root of the exercise folder
+- [ignoring-somethings](https://raw.githubusercontent.com/git-mastery/exercises/refs/heads/main/ignoring_somethings/download.py)
+- [branch-bender](https://raw.githubusercontent.com/git-mastery/exercises/refs/heads/main/branch_bender/download.py)
 
-    ```text
-    <exercise name>
-    ├── .gitmastery-exercise.json
-    ├── README.md
-    ├── <base files> <-- here
-    └── <sub folder name>
-        ├── .git
-        └── ...
-    ```
+### Download conventions
 
-2. Resources: configured through the `__resources__` field in `download.py`; supporting files for the exercise with files located in `res/` downloaded into the sub folder
-
-    ```text
-    <exercise name>
-    ├── .gitmastery-exercise.json
-    ├── README.md
-    ├── <base files>
-    └── <sub folder name>
-        ├── .git
-        └── <resources> <-- here
-    ```
+1. Any operations should use OS agnostic options (e.g. opting to use `shutil.rmtree` over `run_command(["rm"])`)
+2. If you need to compare the states before and after the student has started to add commits, use the given "start tag" as `git-autograder` is designed to read that if necessary
+3. For any commands that require `gh` (Github CLI), make sure that the `requires_github` configuration is set to `true` so that the app will automatically check that the student has correctly setup Github CLI
 
 ### Testing downloads
 
@@ -199,47 +68,15 @@ To test that your download script works, we have provided a script to simulate t
 
 You can find the downloaded repository under the `test-downloads/` folder.
 
-> [!NOTE]
-> If you wish to support a remote repository and require the Git-Mastery team to create a new repository, create an issue and we will assess the request accordingly
-
-
-## Designing verification process 
+## Submitting the hands-on for review
 
-The verification process is controlled by the `verify.py`:
-
-```mermaid
-flowchart
-a[Verify exercise] --> b["Check if in exercise (using .gitmastery-exercise.json)"]
-b -- not in exercise --> c[Cancel]
-b -- in exercise --> d[Execute verification script on exercise folder]
-```
-
-The [`git-autograder`](https://github.com/git-mastery/git-autograder) is built as a wrapper around [`GitPython`](https://github.com/gitpython-developers/GitPython). As a result, if you are writing any verification scripts and there is no available helper function with `git-autograder`, you can fall back to the underlying `Repo` object:
-
-```python
-def verify(exercise: GitAutograderExercise) -> GitAutograderOutput:
-    # Access the underlying GitPython repo:
-    exercise.repo.repo
-
-    return exercise.to_output([], GitAutograderStatus.SUCCESSFUL)
-```
-
-Refer to existing `verify.py` scripts to understand what are the available helper functions to streamline the grading. Open an issue if there is something that is not yet supported or if you have a question.
-
-### Testing verification
-
-To test the verification, we rely on [`repo-smith`](https://github.com/git-mastery/repo-smith) to simulate exercise states and write unit tests to verify the verification script's behavior. You don't need to simulate the entire flow, just the end states that you require for your verification script.
-
-Refer to existing `test_verify.py` to see examples of unit testing the verification script.
-
-You can run the unit tests of your exercise via:
+Create a pull request from your fork using the provided pull request template.
 
-```bash
-./test.sh <your exercise folder>
-```
+Fill in all of the details necessary.
 
-## Submitting the exercise for review
+## Example
 
-Create a pull request from your fork using the provided pull request template.
+1. Hands-on discussion: <https://github.com/git-mastery/exercises/issues/44>
+2. Remote repository request: <https://github.com/git-mastery/exercises/issues/25>
+3. Hands-on PR: 
 
-Fill in all of the details necessary.

index.markdown

@@ -13,4 +13,3 @@ Developer documentation about all things Git-Mastery.
 
 Git-Mastery is a Git education tool developed by the National University of Singapore School of Computing to help students master Git through hands-on, guided tours with real-world scenario exercises.
 
-##