You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Exercises follow a fixed structure for the Git-Mastery app to pick up on:
9
+
10
+
```text
11
+
<exercise name>
12
+
├── .gitmastery-exercise.json
13
+
├── README.md
14
+
├── __init__.py
15
+
├── download.py
16
+
├── res
17
+
│ └── ...
18
+
├── tests
19
+
│ ├── specs
20
+
│ │ └── base.yml
21
+
│ └── test_verify.py
22
+
└── verify.py
23
+
```
24
+
25
+
-`.gitmastery-exercise.json`: contains the exercise configuration
26
+
-`README.md`: contains the instructions for the exercise for the students to attempt
27
+
-`download.py`: contains the download instructions to setup the student's exercise
28
+
-`verify.py`: contains the verification script for the exercise attempt
29
+
-`res/`: contains resources that are available to students (see this section about [types of resources](#types-of-resources))
30
+
-`tests/specs/`: contains specification files written using [`repo-smith`](https://github.com/git-mastery/git-autograder)
31
+
-`tests/test_verify.py`: contains unit tests for verification script
32
+
33
+
## What students see
34
+
35
+
When a student downloads an exercise, they will see the following folder structure:
36
+
37
+
```text
38
+
<exercise name>
39
+
├── .gitmastery-exercise.json
40
+
├── README.md
41
+
└── <sub folder name>
42
+
├── .git
43
+
└── ...
44
+
```
45
+
46
+
The root of the exercise will contain the `README.md` and `.gitmastery-exercise.json` configured from your template.
47
+
48
+
It also contains the sub-folder configured in `.gitmastery-exercise.json`, which is where students will attempt the exercise.
49
+
50
+
## Configuration structure
51
+
52
+
`.gitmastery-exercise.json` is used to tell the [Git-Mastery app](https://git-mastery.github.io/app) how to setup the student's exercise.
53
+
54
+
{: .note }
55
+
56
+
We opted to use a standardized configuration for exercises because they often follow a certain shape for being setup so it is easier if the application
57
+
standardizes the setup via the exercise configuration.
58
+
59
+
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:
60
+
61
+
-`exercise_name`: raw exercise name that will be indexed; recommended to use [kebab case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case)
62
+
-`tags`: used during indexing on the [exercise directory](https://git-mastery.github.io/exercises)
63
+
-`requires_git`: performs a check to ensure that Git is installed and the user has already configured their `user.name` and `user.email`
64
+
-`requires_github`: performs a check to ensure that Github CLI is installed and the user has already authenticated themselves
65
+
-`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]())
66
+
-`exercise_repo`: controls the sub-folder that is generated; this is where students work on the exercise
67
+
-`repo_type`: `local` or `remote`; if `remote`, then the sub-folder is generated from a remote repository
68
+
-`repo_name`: name of the sub-folder; required for both `repo_type`
69
+
-`init`: determines if `git init` is run for the sub-folder; required only for `local`
70
+
-`create_fork`: determines if a fork is created on the user's Github account; required only for `remote`
71
+
-`repo_title`: name of the remote repository to fork + clone; required only for `remote`
72
+
73
+
## Exercise resource types
74
+
75
+
There are two distinct types of resources:
76
+
77
+
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
78
+
79
+
```text
80
+
<exercise name>
81
+
├── .gitmastery-exercise.json
82
+
├── README.md
83
+
├── <base files> <-- here
84
+
└── <sub folder name>
85
+
├── .git
86
+
└── ...
87
+
```
88
+
89
+
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
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:
13
+
12
14
-[ ] Create an [exercise discussion](https://github.com/git-mastery/exercises/issues/new?template=exercise_discussion.yaml)
13
15
-[ ] Obtained approval on the exercise
14
16
-[ ] File a [remote repository request](https://github.com/git-mastery/exercises/issues/new?template=request_exercise_repository.yaml)
15
17
16
-
17
18
## Create a new exercise
18
19
19
20
Use the provided `new.sh` script to generate the scaffolding for a new exercise:
@@ -22,117 +23,40 @@ Use the provided `new.sh` script to generate the scaffolding for a new exercise:
22
23
./new.sh
23
24
```
24
25
25
-
This script will prompt you for:
26
-
27
-
1. The name of the exercise -- likely to be specified in the corresponding exercise discussion
28
-
2. The exercise tags (split by space) -- likely to be specified in the corresponding exercise discussion
29
-
3. The exercise configuration (read the [`.gitmastery-exercise.json` configuration](#gitmastery-exercisejson-configuration) section for more info on this)
30
-
31
-
{: .note }
32
-
33
-
You should use kebab case for the exercise name.
34
-
35
-
It then generates the following directory structure:
36
-
37
-
```text
38
-
<exercise name>
39
-
├── .gitmastery-exercise.json
40
-
├── README.md
41
-
├── __init__.py
42
-
├── download.py
43
-
├── res
44
-
│ └── ...
45
-
├── tests
46
-
│ ├── specs
47
-
│ │ └── base.yml
48
-
│ └── test_verify.py
49
-
└── verify.py
50
-
```
51
-
52
-
-`.gitmastery-exercise.json`: contains the exercise configuration; refer [here](/developers/docs/architecture/gitmastery-exercise-configuration/) for information about the configuration structure
53
-
-`README.md`: contains the instructions for the exercise for the students to attempt
54
-
-`download.py`: contains the download instructions to setup the student's exercise
55
-
-`verify.py`: contains the verification script for the exercise attempt
56
-
-`res/`: contains resources that are available to students (see this section about [types of resources](#types-of-resources))
57
-
-`tests/specs/`: contains specification files written using [`repo-smith`](https://github.com/git-mastery/git-autograder)
58
-
-`tests/test_verify.py`: contains unit tests for verification script
59
-
60
-
## Designing download process
61
-
62
-
The `download.py` contains the instructions to setup the local repository.
63
-
64
-
This is the sequence in which the Git-Mastery app downloads an exercise for a student:
e -- local --> f[Create local repo folder with repo_name]
73
-
e -- remote --> g[Fork repository if toggled]
74
-
g --> h[Clone repository with repo_name]
75
-
f --> i[Download resources]
76
-
h --> i
77
-
i --> j[Create initial commit if init toggled]
78
-
j --> k[Execute download function]
79
-
```
80
-
81
-
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.
82
-
83
-
The default download script comes with a helper function to `run_command` to run local commands.
26
+
The script will first prompt if you want to create a hands-on or exercise:
84
27
85
-
> [!NOTE]
86
-
> You should be using OS-agnostic commands in the download script
28
+
Enter `exercise` or `e` to create a new exercise.
87
29
88
-
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.
30
+
Then, the script will prompt you for:
89
31
90
-
Refer to existing `download.py` for reference on how to setup the download script.
32
+
1. The name of the exercise -- likely to be specified in the corresponding exercise discussion (you should be using kebab case for the exercise name)
33
+
2. The exercise tags (split by space) -- likely to be specified in the corresponding exercise discussion
34
+
3. The exercise configuration (read the [exercise configuration](/developers/docs/architecture/exercise-structure#configuration-structure) section for more info on this)
91
35
92
-
### What students see
36
+
{: .reference }
93
37
94
-
When a student downloads an exercise, they will see the following folder structure:
38
+
Refer to the [exercise structure document](/developers/docs/architecture/exercise-structure) for more information about the folder structure generated.
95
39
96
-
```text
97
-
<exercise name>
98
-
├── .gitmastery-exercise.json
99
-
├── README.md
100
-
└── <sub folder name>
101
-
├── .git
102
-
└── ...
103
-
```
40
+
## Download setup
104
41
105
-
The root of the exercise will contain the `README.md` and `.gitmastery-exercise.json` configured from your template.
42
+
The `download.py` contains the instructions to setup the local repository.
106
43
107
-
It also contains the sub-folder configured in `.gitmastery-exercise.json`, which is where students will attempt the exercise.
44
+
{: .reference }
108
45
109
-
### Types of resources
46
+
For more information about how Git-Mastery downloads exercises, refer to the [Download Workflow](/developers/docs/architecture/download-workflow)
110
47
111
-
There are two distinct types of resources:
48
+
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.
112
49
113
-
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
50
+
These are some references for download setups for other exercises:
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
55
+
### Download conventions
126
56
127
-
```text
128
-
<exercise name>
129
-
├── .gitmastery-exercise.json
130
-
├── README.md
131
-
├── <base files>
132
-
└── <sub folder name>
133
-
├── .git
134
-
└── <resources> <-- here
135
-
```
57
+
1. Any operations should use OS agnostic options (e.g. opting to use `shutil.rmtree` over `run_command(["rm"])`)
58
+
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
59
+
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
136
60
137
61
### Testing downloads
138
62
@@ -144,20 +68,13 @@ To test that your download script works, we have provided a script to simulate t
144
68
145
69
You can find the downloaded repository under the `test-downloads/` folder.
146
70
147
-
> [!NOTE]
148
-
> 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
71
+
## Verification setup
149
72
73
+
The verification process is controlled by the `verify.py`.
150
74
151
-
## Designing verification process
75
+
{: .reference }
152
76
153
-
The verification process is controlled by the `verify.py`:
154
-
155
-
```mermaid
156
-
flowchart
157
-
a[Verify exercise] --> b["Check if in exercise (using .gitmastery-exercise.json)"]
158
-
b -- not in exercise --> c[Cancel]
159
-
b -- in exercise --> d[Execute verification script on exercise folder]
160
-
```
77
+
For more information about how Git-Mastery verifies exercise attempts, refer to the [Verification Workflow](/developers/docs/architecture/verification-workflow)
161
78
162
79
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:
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.
1. Store the comments of the verification as constants so that they can be imported and used reliably in unit tests
99
+
2. For any remote behavior to verify, provide a mock to substitute the behavior in the unit tests
100
+
174
101
### Testing verification
175
102
176
103
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.
0 commit comments