Merge pull request #8 from git-mastery/sub-folder-structure

woojiahao · web-flow · commit a1fa5a7ca42f · 2025-06-21T16:23:38.000+08:00
New exercise config structure
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,23 @@
+name: CI
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  validate_exercise_configurations:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Run validation script
+        run: |
+          python validate-exercise-config.py
diff --git a/README.md b/README.md
@@ -1 +1,27 @@
-# exercises
+# exercises
+
+## Git-Mastery exercise structure
+
+When you download an exercise, you will get the following folder structure:
+
+
+## `.gitmastery-exercise.json`
+
+Configuration fields for each exercise:
+
+1. `exercise_name`: name of exercise
+2. `tags`: list of tags for exercise
+3. `requires_git`: downloading the exercise will check that Git is installed and that `git config` is already done
+4. `requires_github`: downloading the exercise will check that Github and Github CLI is installed
+5. `base_files`: provides the files to be included outside of the repository, along with `.gitmastery-exercise.json` and `README.md`, most often used for `answers.txt`
+6. `exercise_repo`: configuration for what the exercise repository would look like
+    1. `type`: `custom` (creates and initializes the folder as a Git repository) or `link` (reference a repository on Github)
+    2. `name`: name of repository during cloning
+    3. `link`: (only read if `link` is present) link of repository on Github
+    4. `create_fork`: (only read if `link` is present) flag to determine if we need to fork the repository to the student's machine, otherwise it just clones the repository
+    5. `init`: (only read if `custom` is present) flag to determine if we will call `git init` on the exercise repository (useful if we don't want to start out with a Git repository)
+
+
+## TODOs
+
+- [ ] Add validation for exercise configuration (e.g. cannot fork + not require Github) - to run as CI
diff --git a/amateur_detective/.gitmastery-exercise.json b/amateur_detective/.gitmastery-exercise.json
@@ -3,9 +3,14 @@
   "tags": [
     "git-status"
   ],
-  "is_downloadable": true,
-  "requires_repo": true,
-  "resources": {
+  "requires_git": true,
+  "requires_github": false,
+  "base_files": {
     "answers.txt": "answers.txt"
+  },
+  "exercise_repo": {
+    "repo_type": "custom",
+    "repo_name": "crime-scene",
+    "init": true
   }
 }
diff --git a/new-exercise.py b/new-exercise.py
@@ -1,47 +1,100 @@
 import json
 import os
 import pathlib
+import sys
 import textwrap
+from dataclasses import dataclass
+from typing import Dict, List, Literal, Optional
 
-import yaml
 
+@dataclass
+class ExerciseConfig:
+    @dataclass
+    class ExerciseRepoConfig:
+        repo_type: Literal["local", "remote"]
+        repo_name: str
+        repo_title: Optional[str]
+        create_fork: Optional[bool]
+        init: Optional[bool]
 
-def main():
+    exercise_name: str
+    tags: List[str]
+    requires_git: bool
+    requires_github: bool
+    base_files: Dict[str, str]
+    exercise_repo: ExerciseRepoConfig
+
+    def to_json(self) -> str:
+        return json.dumps(self, default=lambda o: o.__dict__, sort_keys=False, indent=2)
+
+    @property
+    def exercise_dir(self) -> pathlib.Path:
+        cur_path = pathlib.Path(os.getcwd())
+        exercise_dir_name = self.exercise_name.replace("-", "_")
+        exercise_dir = cur_path / exercise_dir_name
+        return exercise_dir
+
+
+def confirm(prompt: str, default: bool) -> bool:
+    str_result = input(f"{prompt} (defaults to {'y' if default else 'N'})  [y/N]: ")
+    bool_value = default if str_result.strip() == "" else str_result.lower() == "y"
+    return bool_value
+
+
+def prompt(prompt: str, default: str) -> str:
+    str_result = input(f"{prompt} (defaults to '{default}'): ")
+    if str_result.strip() == "":
+        return default
+    return str_result.strip()
+
+
+def get_exercise_config() -> ExerciseConfig:
     exercise_name = input("Exercise name: ")
     tags_str = input("Tags (space separated): ")
     tags = [] if tags_str.strip() == "" else tags_str.split(" ")
-    requires_repo_str = input("Requires repo? (defaults to y) y/N: ")
-    requires_repo = (
-        requires_repo_str.strip() == ""
-        or requires_repo_str == "y"
-        or requires_repo_str == "Y"
-    )
-    requires_github_str = input("Requires Github? (defaults to y) y/N: ")
-    requires_github = (
-        requires_github_str.strip() == ""
-        or requires_github_str == "y"
-        or requires_github_str == "Y"
+    requires_git = confirm("Requires Git?", True)
+    requires_github = confirm("Requires Github?", True)
+    exercise_repo_type = prompt("Exercise repo type (local or remote)", "local").lower()
+
+    if exercise_repo_type != "local" and exercise_repo_type != "remote":
+        print("Invalid exercise_repo_type, only local and remote allowed")
+        sys.exit(1)
+
+    exercise_repo_name = prompt("Exercise repo name", exercise_name.replace("-", "_"))
+
+    init: Optional[bool] = None
+    create_fork: Optional[bool] = None
+    repo_title: Optional[str] = None
+    if exercise_repo_type == "local":
+        init = confirm("Initialize exercise repo as Git repository?", True)
+    elif exercise_repo_type == "remote":
+        repo_title = prompt("Git-Mastery Github repository title", "")
+        create_fork = confirm("Create fork of repository?", True)
+    return ExerciseConfig(
+        exercise_name=exercise_name,
+        tags=tags,
+        requires_git=requires_git,
+        requires_github=requires_github,
+        base_files={},
+        exercise_repo=ExerciseConfig.ExerciseRepoConfig(
+            repo_type=exercise_repo_type,  # type: ignore
+            repo_name=exercise_repo_name,
+            repo_title=repo_title,
+            create_fork=create_fork,
+            init=init,
+        ),
     )
 
-    cur_path = pathlib.Path(os.getcwd())
-    exercise_dir_name = exercise_name.replace("-", "_")
-    exercise_dir = cur_path / exercise_dir_name
-    os.makedirs(exercise_dir)
-    with open(exercise_dir / ".gitmastery-exercise.json", "w") as exercise_config_file:
-        exercise_config = {
-            "exercise_name": exercise_name,
-            "tags": tags,
-            "is_downloadable": True,
-            "requires_repo": requires_repo,
-            "requires_github": requires_github,
-            "resources": {},
-        }
-        exercise_config_str = json.dumps(exercise_config, indent=2)
-        exercise_config_file.write(exercise_config_str)
-
-    with open(exercise_dir / "README.md", "w") as readme_file:
+
+def create_exercise_config_file(config: ExerciseConfig) -> None:
+    with open(".gitmastery-exercise.json", "w") as exercise_config_file:
+        exercise_config_file.write(config.to_json())
+
+
+def create_readme_file(config: ExerciseConfig) -> None:
+    with open("README.md", "w") as readme_file:
         readme = f"""
-        # {exercise_name}
+        # {config.exercise_name}
 
         <!--- Insert exercise description -->
 
@@ -52,7 +105,7 @@ def main():
         ## Hints
 
         <!--- Insert hints here -->
-        <!--- 
+        <!---
             Use Github Markdown's collapsible content:
             <details>
             <summary>...</summary>
@@ -62,8 +115,10 @@ def main():
         """
         readme_file.write(textwrap.dedent(readme).lstrip())
 
+
+def create_download_py_file() -> None:
     # TODO: conditionally add the git tagging only when requires_repo is True
-    with open(exercise_dir / "download.py", "w") as download_script_file:
+    with open("download.py", "w") as download_script_file:
         download_script = """
         import subprocess
         from sys import exit
@@ -100,9 +155,9 @@ def setup(verbose: bool = False):
         """
         download_script_file.write(textwrap.dedent(download_script).lstrip())
 
-    os.makedirs(exercise_dir / "res", exist_ok=True)
 
-    with open(exercise_dir / "verify.py", "w") as verify_script_file:
+def create_verify_py_file() -> None:
+    with open("verify.py", "w") as verify_script_file:
         verify_script = """
         from typing import List
 
@@ -118,19 +173,25 @@ def verify(repo: GitAutograderRepo) -> GitAutograderOutput:
         """
         verify_script_file.write(textwrap.dedent(verify_script).lstrip())
 
-    open(exercise_dir / "__init__.py", "a").close()
 
-    tests_dir = exercise_dir / "tests"
+def create_init_py_file() -> None:
+    open("__init__.py", "a").close()
+
+
+def create_test_dir(config: ExerciseConfig) -> None:
+    tests_dir = "tests"
     os.makedirs(tests_dir, exist_ok=True)
-    open(tests_dir / "__init__.py", "a").close()
+    os.chdir(tests_dir)
+
+    create_init_py_file()
 
-    with open(tests_dir / "test_verify.py", "w") as test_grade_file:
+    with open("test_verify.py", "w") as test_grade_file:
         test_grade = f"""
         from git_autograder import GitAutograderTestLoader
 
         from ..verify import verify
 
-        REPOSITORY_NAME = "{exercise_name}"
+        REPOSITORY_NAME = "{config.exercise_name}"
 
         loader = GitAutograderTestLoader(__file__, REPOSITORY_NAME, verify)
 
@@ -141,8 +202,8 @@ def test():
         """
         test_grade_file.write(textwrap.dedent(test_grade).lstrip())
 
-    os.makedirs(tests_dir / "specs", exist_ok=True)
-    with open(tests_dir / "specs" / "base.yml", "w") as base_spec_file:
+    os.makedirs("specs", exist_ok=True)
+    with open("specs/base.yml", "w") as base_spec_file:
         base_spec = """
         initialization:
           steps:
@@ -154,5 +215,18 @@ def test():
         base_spec_file.write(textwrap.dedent(base_spec).lstrip())
 
 
+def main():
+    config = get_exercise_config()
+    os.makedirs(config.exercise_dir)
+    os.chdir(config.exercise_dir)
+
+    os.makedirs("res", exist_ok=True)
+    create_exercise_config_file(config)
+    create_readme_file(config)
+    create_download_py_file()
+    create_verify_py_file()
+    create_test_dir(config)
+
+
 if __name__ == "__main__":
     main()
diff --git a/validate-exercise-config.py b/validate-exercise-config.py
@@ -0,0 +1,98 @@
+# Script to verify that all exercise configurations are compliant with the expected format
+import json
+import os
+import pathlib
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import List
+
+# List of exercises to exempt, maybe because these have not been updated or are deprecated exercises
+EXEMPTION_LIST = {
+    "grocery_shopping",
+    "ignoring_somethings",
+    "link_me",
+    "nothing_to_hide",
+    "push_over",
+    "remote_control",
+    "stage_fright",
+    "under_control",
+}
+
+
+@dataclass
+class ValidationIssue:
+    dir_name: str
+    issue: str
+
+
+def main() -> None:
+    issues: List[ValidationIssue] = []
+    for dir in os.listdir("."):
+        if dir in EXEMPTION_LIST or not os.path.isfile(
+            pathlib.Path(dir) / ".gitmastery-exercise.json"
+        ):
+            continue
+        config = {}
+        with open(pathlib.Path(dir) / ".gitmastery-exercise.json", "r") as config_file:
+            config = json.loads(config_file.read())
+
+            if config["exercise_name"].strip() == "":
+                issues.append(
+                    ValidationIssue(dir, "Empty exercise_name is not permitted")
+                )
+
+            if config.get("exercise_repo", {}).get(
+                "repo_type", "local"
+            ) == "remote" and not config.get("requires_github", False):
+                issues.append(
+                    ValidationIssue(
+                        dir,
+                        "Cannot use 'remote' repo_type if require_github is disabled",
+                    )
+                )
+
+            if (
+                config.get("exercise_repo", {}).get("repo_type", "local") == "local"
+                and not config.get("requires_git", False)
+                and config.get("exercise_repo", {}).get("init", False)
+            ):
+                issues.append(
+                    ValidationIssue(
+                        dir,
+                        "Cannot use 'local' repo_type with init: true if require_git is disabled",
+                    )
+                )
+
+            if (
+                config.get("exercise_repo", {}).get("repo_type", "local") == "remote"
+                and subprocess.call(
+                    [
+                        "git",
+                        "ls-remote",
+                        f"https://github.com/git-mastery/{config['exercise_repo']['repo_title']}",
+                        "--quiet",
+                    ]
+                )
+                != 0
+            ):
+                issues.append(
+                    ValidationIssue(
+                        dir, "Missing Github repository to fetch for remote exercise"
+                    )
+                )
+
+            for file in config["base_files"].keys():
+                if not os.path.isfile(pathlib.Path(dir) / "res" / file):
+                    issues.append(
+                        ValidationIssue(dir, f"Missing file {file} from res/")
+                    )
+
+    if len(issues) > 0:
+        for issue in issues:
+            print(f"- {issue.dir_name}: {issue.issue}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
