1. What is a hands-on?
  2. Before contributing
  3. Implementing a hands-on
    1. Conventions
    2. Testing downloads
  4. Submitting the hands-on for review
  5. Example

What is a hands-on?

Lessons accompanying Git-Mastery App contains hands-on practicals for students to get ‘hands-on’ experience of the Git concepts covered by the lesson. Some of those hands-on practicals need to set up a ‘sandbox’ containing the required folders, files, repos before the student can do the practical. Git-Mastery app can set up that sandbox for students so that they can get to the ‘practical’ part more easily (we refer to this as ‘downloading’ the hands-on), without having to set up the sandbox manually. For example, a student can run gitmastery download <hands-on name> (e.g., gitmastery download hp-init-repo) to set up the sandbox for a specific hands-on practical.

Some examples of how Git-Mastery app helps to create the sandbox for a hands-on practical can be seen in this Git Tour (see T1L3, T1L4).

Before contributing

New contributors are recommended to start by implementing an already approved hands-on proposal.

If you are proposing a new hands-on instead, make sure that you have done the following:

Implementing a hands-on

First, run the provided new.sh script to generate the scaffolding for a new hands-on sandbox:

./new.sh

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

Enter hands-on or h to create a new hands-on.

Then, the script will prompt you for:

  1. The name of the hands-on – likely to be specified in the corresponding hands-on discussion (without the hp- prefix!) (you should be using kebab case for the hands-on name)
  2. Does the hands-on require Git?
  3. Does the hands-on require Github?

Refer to the hands-on structure document for more information about the folder structure generated.

Each hands-on is implemented as a single file hands_on/<hands-on name>.py, containing the instructions to set up the hands-on sandbox .

For more information about how Git-Mastery downloads a hands-on, refer to the Download Workflow

exercises repo 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:

Conventions

  1. Any operations should use OS-agnostic options (e.g. opting to use shutil.rmtree over run_command(["rm"]))
  2. For any commands that require gh (GitHub CLI), make sure that the __requires_github__ variable in the download setup 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 <hands-on name>

You can find the sandbox created by the script under the test-downloads/ folder. Check it manually to verify it is as expected.

Submitting the hands-on for review

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

Fill in all the details necessary.

Example

  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: https://github.com/git-mastery/exercises/pull/45