Merge pull request #20 from i-walk-away/content

guidelines for contributors

Author: i-walk-away

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing
+
+Table of contents!
+
+## Adding new lessons to pydantic quest
+
+If you want to add a new lesson to pydantic quest, do this:
+
+1. Create a new folder in [lessons/](lessons/)
+2. Populate the folder with 4 neccessary files. You can copy them from
+   [lessons/lesson-template/](lessons/lesson-template/):
+    * `lesson.yaml`
+    * `theory.md`
+    * `starter.py`
+    * `cases.yaml`
+3. Head to [lessons/index.yaml](lessons/index.yaml) and add the following:
+
+```yaml
+  - slug: dash-separated-lesson-name
+    order: <integer>
+```
+
+The "order" field changes the order in which lessons appear in pydantic quest.
+If you're not sure, just use whatever highest order already exists in index and
+add +1 to it. I will reorder everything myself if needed :)
+
+## Explanation of the 4 neccessary files
+
+### 1. `lesson.yaml`
+
+This file currently only defines the name of the lesson. The file has the following structure:
+
+```yaml
+title: "Your lesson title goes here"
+```
+
+Change the `title` field to the title of your lesson.
+
+### 2. `theory.md`
+
+The contents of this file is the lesson *body:* what the user sees on the
+left side of the screen when your lesson is selected.
+Populate it with theoretical information and an assignment.
+Refer to [lessons/lesson-template/theory.md](lessons/lesson-template/theory.md) to see available
+custom formatting (on top of existing Markdown formatting)
+and general recommendations on designing a good lesson body.
+
+### 3. `starter.py`
+
+The contents of this python script is what will be displayed to the user in the code editor
+by default in your lesson.
+The user will then build upon your starter script in order to complete the assignment.
+Refer to [lessons/lesson-template/starter.py](lessons/lesson-template/starter.py) for better insight.
+
+### 4. `cases.yaml`
+
+Test cases for your lesson. Just refer to [`lessons/lesson-template/cases.yaml`](lessons/lesson-template/cases.yaml).
+You can find
+a *lot* of information there about how it works and how exactly to design your own test cases.
+Please inform me if it is still not very clear.
+
+## Contributor checklist
+
+Before opening a PR:
+
+1. verify `lesson.yaml`, `theory.md`, `starter.py`, and `cases.yaml` exist in your new lesson folder
+2. verify lesson slug is added to [lessons/index.yaml](lessons/index.yaml)
+3. confirm each visible case has clear `label` and useful `reason`

lessons/intro-model/theory.md

@@ -1,5 +1,3 @@
-# Intro: BaseModel and validation
-
 Create a `User` model with fields:
 
 - name: `str`

lessons/lesson-template/cases.yaml

@@ -1,36 +1,201 @@
 cases:
-  # each case has:
-  # - unique "name" (internal id)
-  # - readable "label" (shown to learner for visible cases)
-  # - hidden=true/false
-  # - script that sets boolean "ok" and optional "reason"
+  # This file defines the automated checks that run against the learner's submitted code.
+  #
+  # Read this file as "a list of small python programs". Each item under
+  # "cases" is executed separately after the learner's solution has already been
+  # loaded into memory.
+  #
+  # Execution model:
+  # - the learner writes code in the code edtor
+  # - the platform executes that code first
+  # - after that, each case below runs as its own small Python script
+  # - those scripts can access objects created by the learner in his python programm
+  # (for example, if user has created a UserProfile class - your scripts can access it
+  #
+  # That is why cases below can use "UserProfile" directly even though this YAML file
+  # never defines it. "UserProfile" is expected to come from the learner's
+  # submission. In a real lesson, replace "UserProfile" with whatever object,
+  # function, validator, or model the learner is supposed to build.
+  #
+  # In other words:
+  # This file describes how the platform will verify the solution.
+  # Lesson-defined names come from the learner's code.
+  # Your overall goal here is to write small tests that will verify the correctness of
+  # the user's solution. If your lesson is about making a UserProfile class with
+  # the field "age: int" and a strict requirement:
+  #
+  # "String age should raise ValidationError, even though Pydantic usually
+  # converts string numbers to integers when they're assigned
+  # to integer fields",
+  #
+  # then you should create a test case that tries to instantiate UserProfile with string age
+  # and if no ValidationError exception is raised by the user - and therefore is not
+  # caught in your script's `try / except` block - this case should fail, because
+  # you just verified that the submitted UserProfile definition is not raising
+  # a validation error upon receiving a string type age. You get the idea.
+  #
+  # Every case item has four fields:
+  #
+  # name:
+  #   Stable internal identifier of a test case.
+  #   Requirements:
+  #   - must be unique inside this file
+  #   - should use snake_case
+  #   - should describe the rule being tested (e.g "string_age")
+  #
+  # label:
+  #   Short human-readable title for the case.
+  #   Unless your test case is hidden (more info below), the user will see this label
+  #     upon unfolding the "test cases" list at the end of the lesson body.
+  #
+  #   Good labels describe what is tested:
+  #   - "string age rejected"
+  #   - "username stripped"
+  #
+  #   Bad labels:
+  #   - "string age"
+  #   - "strip username"
+  #   - "test field validator"
+  #
+  # hidden (bool):
+  #   Controls whether the case is visible in the UI before the learner runs the
+  #   solution.
+  #   - false: visible to the learner in the public "test cases" list
+  #   - true: still executed, but hidden from the public list
+  #
+  # script:
+  #   Python code for this specific test case.
+  #   It runs in the same execution context as the learner's code, so it can:
+  #   - instantiate learner-defined classes
+  #   - call learner-defined functions
+  #   - inspect returned values
+  #   - intentionally trigger validation or runtime errors
+  #
+  # The platform expects each script to communicate the result through these
+  # variables:
+  # - ok:
+  #     required boolean pass/fail flag
+  # - reason:
+  #     optional string explaining why the case failed
+  #
+  # If your script raises an exception and you do NOT catch it yourself, the
+  # platform catches it at the case-runner level and automatically converts it
+  # into a failed case:
+  # - ok becomes False
+  # - reason becomes "<ExceptionClass>: <exception text>"
+  #
+  # For example, if this line raises a Pydantic ValidationError:
+  #   profile = UserProfile(username="alice", age=24, tags=["some_string"])
+  # then the case will fail automatically with a reason similar to:
+  #   ValidationError: 1 validation error for UserProfile
+  #
+  # This means:
+  # - uncaught exceptions do NOT crash the whole runner
+  # - they fail only the current case
+  # - if you want an exception to count as a successful validation check, wrap
+  #   the code in try/except and set ok/reason yourself. like this:
+  #
+  #     try:
+  #         <if this line of code doesn't raise a ValidationError, the rest of the try block will execute>
+  #         ok = False
+  #         reason = "invalid input must raise validation error"
+  #     except ValidationError:
+  #         ok = True
+  #
+  # Practical rule:
+  # - if the case passes, setting only "ok = True" is enough
+  # - if the case fails, set "ok = False" and provide a short "reason"
+  #     (e.g "passing a `string` value to `age` field of UserProfile should
+  #     raise ValidationError)
+  #
+  # Write "reason" as direct feedback to the learner. It should
+  # explain the broken behavior, not narrate the script:
+  # - good: "blank username must raise validation error"
+  # - good: "age boundary value 13 should be accepted"
+  # - bad: "the assertion failed"
+  # - bad: "string age test returned false"
+  #
+  # Recommended lesson design strategy:
+  # - use visible cases for the actual contract the learner should implement:
+  #     valid input, invalid input, boundary values, normalization rules, and
+  #     anything else you want them to understand explicitly from the lesson
+  #
+  # - use hidden cases mostly for anti-cheat and anti-hardcode coverage
+  # - do not hide test cases that are important fot teaching the subject
+  #
+  # Some ideas for your test cases (doesn't apply to everything, of course):
+  # - invalid input
+  # - visible edge and boundary cases
+  # - off-by-one errors
+  # - missing fields
+  # - wrong types
+  # - multiple invalid combinations
+  # - one hidden anti-hardcode case, if the lesson needs it
+  #
+  # Keep each case focused. Prefer five small cases over one giant script that
+  # tries to test everything at once. Small cases are easier to read, debug, and
+  # maintain.
+  #
+  # Visible happy path.
+  #
+  # Use at least one public case that demonstrates what "correct" looks like.
+  # The learner should be able to run their code and quickly confirm the core
+  # behavior works before dealing with edge cases.
 
-  # visible "happy path": keep at least one simple success case for fast feedback
   - name: valid_profile
     label: valid profile
     hidden: false
     script: |
-      profile = UserProfile(username="alice", age=24, tags=["python"])
-      ok = profile.username == "alice" and profile.age == 24 and profile.tags == ["python"]
+      # "UserProfile" is expected to be created by the learner in starter.py.
+      # This case does not define that class. It assumes the learner's code has
+      # already defined it and now verifies its happy-path behavior.
+      #
+      # If the learner forgot to define one of the required fields, or defined a
+      # different schema that cannot accept these values, this constructor call
+      # may raise an exception. If that happens and you do not catch it here,
+      # the platform will automatically fail this case and turn the exception
+      # into the case fail reason, so you don't have to test manually if fields actually
+      # exist:
+      profile = UserProfile(username="alice", age=24, tags=["some_string"])
+
+      # Set ok to a boolean. The platform reads this variable to determine
+      # whether the case passed.
+      ok = profile.username == "alice" and profile.age == 24 and profile.tags == ["some_string"]
+
+      # "reason" should explain the actual contract that was broken.
+      # The learner sees this message if ok is False, so it should be specific
+      # enough to tell them what to fix.
       if not ok:
-          reason = "model should accept valid data and preserve field values"
+          reason = "model should define all required fields with the correct types and accept valid input"
 
-  # visible "negative path": learner immediately sees why solution is incomplete
+  # Negative path.
+  #
+  # Failure cases are useful because they explain the lesson's rules
+  # immediately. Here we say that blank usernames must not be accepted.
   - name: reject_blank_username
     label: reject blank username
     hidden: false
     script: |
+      # This case expects invalid input to be rejected.
+      #
+      # Use try/except for rules where "raising an exception" is the expected
+      # success condition.
       try:
           UserProfile(username="   ", age=24, tags=[])
           ok = False
           reason = "blank username must raise validation error"
       except Exception:
+          # An exception means the invalid input was rejected, so the case
+          # passes. It's better if you check for an exact exception type
+          # or inspect the error message.
           ok = True
 
-  # hidden anti-cheat/edge case: not shown in sample list
+  # Visible validation rule.
+  #
+  # If "age must be at least 13" is part of the lesson contract.
   - name: reject_too_young
     label: reject age under 13
-    hidden: true
+    hidden: false
     script: |
       try:
           UserProfile(username="alice", age=12, tags=[])
@@ -39,22 +204,55 @@ cases:
       except Exception:
           ok = True
 
-  # hidden boundary check: catches off-by-one bugs
+  # Boundary check.
+  #
+  # Boundary cases are valuable because they catch off-by-one mistakes.
+  # If the rule is "age must be at least 13", you should test 13 too.
   - name: accept_boundary_age
     label: accept boundary age
-    hidden: true
+    hidden: false
     script: |
+      # Boundary checks catch common "> vs >=" and "< vs <=" mistakes.
       profile = UserProfile(username="alice", age=13, tags=[])
       ok = profile.age == 13
       if not ok:
           reason = "age boundary value 13 should be accepted"
 
-  # hidden normalization case: useful when lesson requires sanitizing strings
-  - name: trim_username
-    label: trim username
-    hidden: true
+  # Normalization case.
+  #
+  # Use cases like this when the learner must normalize or clean input data.
+  # This prevents solutions that only validate but do not transform values.
+  - name: username_trimmed
+    label: username trimmed
+    hidden: false
     script: |
+      # This case shows how to test normalization instead of pure validation.
+      # If the lesson expects cleaned output, assert on the transformed value.
+      
       profile = UserProfile(username="  alice  ", age=24, tags=[])
+      
+      # If the model is defined correctly, username will be trimmed upon instantiating profile.
+      # Therefore the value of profile.username should be processed (trimmed in this case) 
+      
       ok = profile.username == "alice"
       if not ok:
           reason = "username should be normalized with strip()"
+
+  # Hidden anti-hardcode example.
+  #
+  # This is a good example of when a hidden case is justified: it checks the
+  # same contract as the visible happy path, but with different values. That
+  # makes it harder to pass the lesson with a hardcoded object or with logic
+  # that only works for one specific input sample shown publicly.
+  - name: valid_profile_different_values
+    label: valid profile with different values
+    hidden: true
+    script: |
+      profile = UserProfile(username="bob", age=31, tags=["fastapi", "backend"])
+      ok = (
+          profile.username == "bob"
+          and profile.age == 31
+          and profile.tags == ["fastapi", "backend"]
+      )
+      if not ok:
+          reason = "model should work for valid input values beyond the public example"

lessons/lesson-template/lesson.yaml

@@ -1 +1 @@
-title: "Template: How to write a lesson"
+title: "Your lesson title goes here"