1. Before contributing
2. Create a new exercise
3. Download setup
   1. Download conventions
   2. Testing downloads
4. Verification setup
   1. Verification conventions
   2. Testing verification
5. Submitting the exercise for review
6. Example

Before contributing

If you are proposing a new exercise (i.e., not implementing an already approved exercise proposal) make sure that you have done the following:

• Create an exercise discussion
• Obtain approval on the exercise
• File a remote repository request

Create a new exercise

Use the provided new.sh script to generate the scaffolding for a new exercise:

./new.sh

The script will first prompt if you want to create a hands-on or exercise:

Enter exercise or e to create a new exercise.

Then, the script will prompt you for:

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)
2. The exercise tags (split by space) – likely to be specified in the corresponding exercise discussion
3. The exercise configuration (read the exercise configuration section for more info on this)

Refer to the exercise structure document for more information about the folder structure generated.

Download setup

The download.py contains the instructions to setup the local repository.

For more information about how Git-Mastery downloads exercises, refer to the Download Workflow

exercises comes with a set of utility functions in the exercise_utils module that are made available during the download flow. They provide simple wrappers around common functionality such as exercise_utils.cli.run_command to invoke any command and exercise_utils.file.create_or_update_file to create or update a given file.

For the full list of utility functions, refer here.

These are some references for download setups for other exercises:

• ignoring-somethings
• branch-bender
• amateur-detective

Download conventions

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

To test that your download script works, we have provided a script to simulate the download process in this repository for you to verify.

./test-download.sh <your exercise folder>

You can find the downloaded repository under the test-downloads/ folder.

Verification setup

The verification process is controlled by the verify.py.

For more information about how Git-Mastery verifies exercise attempts, refer to the Verification Workflow

The git-autograder is built as a wrapper around 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:

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.

Some examples of verifications:

• branch-bender
• conflict-mediator

Verification conventions

1. Store the comments of the verification as constants so that they can be imported and used reliably in unit tests
2. For any remote behavior to verify, provide a mock to substitute the behavior in the unit tests

Testing verification

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.

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:

./test.sh <your exercise folder>

Submitting the exercise for review

Create a pull request from your fork using the provided pull request template.

Fill in all of the details necessary.

Example

1. Exercise discussion: https://github.com/git-mastery/exercises/issues/24
2. Remote repository request: https://github.com/git-mastery/exercises/issues/25
3. Exercise PR: https://github.com/git-mastery/exercises/pull/26