|
| 1 | +--- |
| 2 | +title: Exercise |
| 3 | +parent: Contributing |
| 4 | +nav_order: 2 |
| 5 | +--- |
| 6 | + |
| 7 | +# Contributing an exercise |
| 8 | + |
| 9 | +## Before contributing |
| 10 | + |
| 11 | +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: |
| 12 | +- [ ] Create an [exercise discussion](https://github.com/git-mastery/exercises/issues/new?template=exercise_discussion.yaml) |
| 13 | +- [ ] Obtained approval on the exercise |
| 14 | +- [ ] File a [remote repository request](https://github.com/git-mastery/exercises/issues/new?template=request_exercise_repository.yaml) |
| 15 | + |
| 16 | + |
| 17 | +## Create a new exercise |
| 18 | + |
| 19 | +Use the provided `new.sh` script to generate the scaffolding for a new exercise: |
| 20 | + |
| 21 | +```bash |
| 22 | +./new.sh |
| 23 | +``` |
| 24 | + |
| 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: |
| 65 | + |
| 66 | +```mermaid |
| 67 | +flowchart |
| 68 | +a[Download exercise] --> b[Create exercise folder] |
| 69 | +b --> c[Download base files to exercise root] |
| 70 | +c --> d[Check Git if toggled] |
| 71 | +d --> e[Check Github if toggled] |
| 72 | +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. |
| 84 | + |
| 85 | +> [!NOTE] |
| 86 | +> You should be using OS-agnostic commands in the download script |
| 87 | +
|
| 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. |
| 89 | + |
| 90 | +Refer to existing `download.py` for reference on how to setup the download script. |
| 91 | + |
| 92 | +### What students see |
| 93 | + |
| 94 | +When a student downloads an exercise, they will see the following folder structure: |
| 95 | + |
| 96 | +```text |
| 97 | +<exercise name> |
| 98 | +├── .gitmastery-exercise.json |
| 99 | +├── README.md |
| 100 | +└── <sub folder name> |
| 101 | + ├── .git |
| 102 | + └── ... |
| 103 | +``` |
| 104 | + |
| 105 | +The root of the exercise will contain the `README.md` and `.gitmastery-exercise.json` configured from your template. |
| 106 | + |
| 107 | +It also contains the sub-folder configured in `.gitmastery-exercise.json`, which is where students will attempt the exercise. |
| 108 | + |
| 109 | +### Types of resources |
| 110 | + |
| 111 | +There are two distinct types of resources: |
| 112 | + |
| 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 |
| 114 | + |
| 115 | + ```text |
| 116 | + <exercise name> |
| 117 | + ├── .gitmastery-exercise.json |
| 118 | + ├── README.md |
| 119 | + ├── <base files> <-- here |
| 120 | + └── <sub folder name> |
| 121 | + ├── .git |
| 122 | + └── ... |
| 123 | + ``` |
| 124 | +
|
| 125 | +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 |
| 126 | +
|
| 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 | + ``` |
| 136 | +
|
| 137 | +### Testing downloads |
| 138 | +
|
| 139 | +To test that your download script works, we have provided a script to simulate the download process in this repository for you to verify. |
| 140 | +
|
| 141 | +```bash |
| 142 | +./test-download.sh <your exercise folder> |
| 143 | +``` |
| 144 | + |
| 145 | +You can find the downloaded repository under the `test-downloads/` folder. |
| 146 | + |
| 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 |
| 149 | +
|
| 150 | + |
| 151 | +## Designing verification process |
| 152 | + |
| 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 | +``` |
| 161 | + |
| 162 | +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: |
| 163 | + |
| 164 | +```python |
| 165 | +def verify(exercise: GitAutograderExercise) -> GitAutograderOutput: |
| 166 | + # Access the underlying GitPython repo: |
| 167 | + exercise.repo.repo |
| 168 | + |
| 169 | + return exercise.to_output([], GitAutograderStatus.SUCCESSFUL) |
| 170 | +``` |
| 171 | + |
| 172 | +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. |
| 173 | + |
| 174 | +### Testing verification |
| 175 | + |
| 176 | +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. |
| 177 | + |
| 178 | +Refer to existing `test_verify.py` to see examples of unit testing the verification script. |
| 179 | + |
| 180 | +You can run the unit tests of your exercise via: |
| 181 | + |
| 182 | +```bash |
| 183 | +./test.sh <your exercise folder> |
| 184 | +``` |
| 185 | + |
| 186 | +## Submitting the exercise for review |
| 187 | + |
| 188 | +Create a pull request from your fork using the provided pull request template. |
| 189 | + |
| 190 | +Fill in all of the details necessary. |
0 commit comments