Skip to content

Commit 336b717

Browse files
woojiahaowoojiahao
committed
[contributing] Update contributing structure
1 parent 3a025ee commit 336b717

File tree

1 file changed

+91
-69
lines changed

1 file changed

+91
-69
lines changed

‎.github/CONTRIBUTING.md‎

Lines changed: 91 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,25 @@
1+
[![CI](https://github.com/git-mastery/exercises/actions/workflows/ci.yml/badge.svg)](https://github.com/git-mastery/exercises/actions/workflows/ci.yml)
2+
13
# Contributing an exercise
24

5+
## Before contributing
6+
7+
Make sure that you have done the following:
8+
9+
- [ ] Create an [exercise discussion](https://github.com/git-mastery/exercises/issues/new?template=exercise_discussion.yaml)
10+
- [ ] Obtained approval on the exercise
11+
- [ ] File a [remote repository request](https://github.com/git-mastery/exercises/issues/new?template=request_exercise_repository.yaml)
12+
313
## Prerequisites
414

515
- Bash environment
616
- Python 3.13
7-
- `gh` Github CLI [installed and authenticated](https://github.com/cli/cli#installation) for testing downloads
17+
- Github CLI [installed and authenticated](https://github.com/cli/cli#installation) for testing the download script
818

9-
## Getting started
19+
## Setup
1020

11-
1. Fork the repository
12-
2. Clone the repository
21+
1. Fork this repository
22+
2. Clone the fork
1323

1424
```bash
1525
git clone https://github.com/<username>/exercises
@@ -33,89 +43,49 @@
3343
pip install -r requirements.txt
3444
```
3545

36-
6. Create a new exercise template, following the prompts to setup the `.gitmastery-exercise.json` configuration file. For more details about the configuration, refer [here]()
46+
## Create a new exercise
3747

38-
```bash
39-
./new.sh
40-
```
48+
Use the provided `new.sh` script to scaffold a new exercise:
4149

50+
```bash
51+
./new.sh
52+
```
4253

43-
You should now see a new exercise with the name you have chosen.
54+
This script will prompt you for:
4455

45-
## Exercise structure
56+
1. The name of the exercise
57+
2. The exercise tags (split by space)
58+
3. The exercise configuration
4659

47-
### Your template
60+
> [!TIP]
61+
> You should use kebab case for the exercise name.
4862

49-
An exercise comprises of the following structure:
63+
It then generates the following directory structure:
5064

5165
```text
5266
<exercise name>
67+
├── .gitmastery-exercise.json
5368
├── README.md
5469
├── __init__.py
5570
├── download.py
5671
├── res
5772
│ └── ...
5873
├── tests
59-
│ ├── __init__.py
6074
│ ├── specs
61-
│ │ ├── base.yml
75+
│ │ └── base.yml
6276
│ └── test_verify.py
6377
└── verify.py
6478
```
6579

80+
- `.gitmastery-exercise.json`: contains the exercise configuration
6681
- `README.md`: contains the instructions for the exercise for the students to attempt
6782
- `download.py`: contains the download instructions to setup the student's exercise
6883
- `verify.py`: contains the verification script for the exercise attempt
6984
- `res/`: contains resources that are available to students (see this section about [types of resources](#types-of-resources))
7085
- `tests/specs/`: contains specification files written using [`repo-smith`](https://github.com/git-mastery/git-autograder)
7186
- `tests/test_verify.py`: contains unit tests for verification script
7287
73-
### What students see
74-
75-
When a student downloads an exercise, they will see the following folder structure:
76-
77-
```text
78-
<exercise name>
79-
├── .gitmastery-exercise.json
80-
├── README.md
81-
└── <sub folder name>
82-
├── .git
83-
└── ...
84-
```
85-
86-
The root of the exercise will contain the `README.md` and `.gitmastery-exercise.json` configured from your template.
87-
88-
It also contains the sub-folder configured in `.gitmastery-exercise.json`, which is where students will attempt the exercise.
89-
90-
## Types of resources
91-
92-
There are two distinct types of resources:
93-
94-
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
95-
96-
```text
97-
<exercise name>
98-
├── .gitmastery-exercise.json
99-
├── README.md
100-
├── <base files>
101-
└── <sub folder name>
102-
├── .git
103-
└── ...
104-
```
105-
106-
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
107-
108-
```text
109-
<exercise name>
110-
├── .gitmastery-exercise.json
111-
├── README.md
112-
├── <base files>
113-
└── <sub folder name>
114-
├── .git
115-
└── <resources>
116-
```
117-
118-
## `.gitmastery-exercise.json` configuration
88+
### `.gitmastery-exercise.json` configuration
11989
12090
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.
12191

@@ -127,13 +97,13 @@ The `new.sh` script should have already generated one for you, but you may chang
12797
- `requires_github`: performs a check to ensure that Github CLI is installed and the user has already authenticated themselves
12898
- `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]())
12999
- `exercise_repo`: controls the sub-folder that is generated; this is where students work on the exercise
130-
- `repo_type`: `local` or `remote`; if `remote`, then the sub-folder is generated from a remote repository
131-
- `repo_name`: name of the sub-folder; required for both `repo_type`
132-
- `init`: determines if `git init` is run for the sub-folder; required only for `local`
133-
- `create_fork`: determines if a fork is created on the user's Github account; required only for `remote`
134-
- `repo_title`: name of the remote repository to fork + clone; required only for `remote`
100+
- `repo_type`: `local` or `remote`; if `remote`, then the sub-folder is generated from a remote repository
101+
- `repo_name`: name of the sub-folder; required for both `repo_type`
102+
- `init`: determines if `git init` is run for the sub-folder; required only for `local`
103+
- `create_fork`: determines if a fork is created on the user's Github account; required only for `remote`
104+
- `repo_title`: name of the remote repository to fork + clone; required only for `remote`
135105
136-
## Download script
106+
## Designing download process
137107
138108
The `download.py` contains the instructions to setup the local repository.
139109
@@ -165,6 +135,51 @@ The initial download script also includes a command to attach a tag as the "star
165135

166136
Refer to existing `download.py` for reference on how to setup the download script.
167137

138+
### What students see
139+
140+
When a student downloads an exercise, they will see the following folder structure:
141+
142+
```text
143+
<exercise name>
144+
├── .gitmastery-exercise.json
145+
├── README.md
146+
└── <sub folder name>
147+
├── .git
148+
└── ...
149+
```
150+
151+
The root of the exercise will contain the `README.md` and `.gitmastery-exercise.json` configured from your template.
152+
153+
It also contains the sub-folder configured in `.gitmastery-exercise.json`, which is where students will attempt the exercise.
154+
155+
### Types of resources
156+
157+
There are two distinct types of resources:
158+
159+
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
160+
161+
```text
162+
<exercise name>
163+
├── .gitmastery-exercise.json
164+
├── README.md
165+
├── <base files> <-- here
166+
└── <sub folder name>
167+
├── .git
168+
└── ...
169+
```
170+
171+
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
172+
173+
```text
174+
<exercise name>
175+
├── .gitmastery-exercise.json
176+
├── README.md
177+
├── <base files>
178+
└── <sub folder name>
179+
├── .git
180+
└── <resources> <-- here
181+
```
182+
168183
### Testing downloads
169184

170185
To test that your download script works, we have provided a script to simulate the download process in this repository for you to verify.
@@ -178,9 +193,10 @@ You can find the downloaded repository under the `test-downloads/` folder.
178193
> [!NOTE]
179194
> 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
180195

181-
## Verification script
182196

183-
The verification process is a simpler on the Git-Mastery app:
197+
## Designing verification process
198+
199+
The verification process is controlled by the `verify.py`:
184200

185201
```mermaid
186202
flowchart
@@ -203,7 +219,7 @@ Refer to existing `verify.py` scripts to understand what are the available helpe
203219

204220
### Testing verification
205221

206-
To test the verification, we rely on `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.
222+
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.
207223

208224
Refer to existing `test_verify.py` to see examples of unit testing the verification script.
209225

@@ -212,3 +228,9 @@ You can run the unit tests of your exercise via:
212228
```bash
213229
./test.sh <your exercise folder>
214230
```
231+
232+
## Submitting the exercise for review
233+
234+
Create a pull request from your fork using the provided pull request template.
235+
236+
Fill in all of the details necessary.

0 commit comments

Comments
 (0)