Move to cmt 2 (#82)

* Move to CMT 2.0

* The exercise on compiler code rewrite should contain the rewritten code

- Code is rewritten to indentation based syntax and new control structure
  syntax

* Add build definitions to remaining exercises

* Fix pattern match issue in exercise on multiversal equality

* Add CMT 2 configuration file

* Update exercise instructions for the initial state exercise

* Update exercise on compiler code rewriting for Scala 2 migrations

* Update instructions for the exercise on syntax rewriting

* Minor update to initial state exercise instructions

* Update build - Remove unused definition/bump Akka version

- Remove unused value definition in build definition
- Bump Akka version
- Change vals to lazy

* Fix build

* Update exercise instructions

* Adapt modified syntax for wildcard imports

* The exercise on deprecated syntax rewriting contains the result

* Shorten exercise titles

* Change CI in view of switch to CMT 2

* Remove redundant CMT 1 files

- As the project is moved to a CMT 2 project structure, the CMT 1
  specific stuff can be removed

* Update versions of Github actions

* Update CI

- Github actions 'set-output' is deprecated

* Revert change to CI

* Use integrated caching in actions/setup-java@v3

* Add compiler option "-source:future-migration" from second exercise onward

* Update exercise instructions

Exercises on:

- parameter tupling
- extension methods

* Update build status check

* Update exercise instructions for contextual abstractions exercise

- Update to `using`/`summon`

* Update exercise instructions for contextual abstractions exercise II

- Use `given` where appropriate

* Update enum exercise instructions

* Update instructions for exercise on Union types

* Fix remaining warning in test for some exercises

* Remove implicit conversion import as it isn't needed

- From some unclear reason, there are a couple of instances of
  `scala.language.implicitConversions` in both main and test
  code that are completely unnecessary. Removed them from the
  Scala 2 code (first exercise - Initial State)

* Remove implicit conversion import as it isn't needed

- For some unclear reason, there are a couple of instances of
  `scala.language.implicitConversions` in both main and test
  code that are completely unnecessary. Removed them from the
  Scala 3 code (second exercise onwards)

* Update formatting of code

* Apply () instead of the deprecated auto-application to ()

* Update logback configuration

Author: eloots

.github/workflows/ci.yml

@@ -7,51 +7,48 @@ on:
   pull_request:
     branches: [ main ]
 
+env:
+  EXERCISES_DIRECTORY: ./exercises
+
 jobs:
+  list-exercises:
+    runs-on: ubuntu-latest
+    outputs:
+      exercises: ${{steps.list.outputs.exercises}}
+    steps:
+      - uses: actions/checkout@v3
+      - id: list
+        run: echo "::set-output name=exercises::$(ls $EXERCISES_DIRECTORY | grep exercise_ | jq -cnR '[inputs | select(length>0)]')"
+#        run: echo "name=exercises::$(ls $EXERCISES_DIRECTORY | grep exercise_ | jq -cnR '[inputs | select(length>0)]')" >> $GITHUB_OUTPUT
+
   validate_course:
     runs-on: ubuntu-latest
+    needs: list-exercises
+    strategy:
+      fail-fast: false
+      matrix:
+        exercise: ${{fromJson(needs.list-exercises.outputs.exercises)}}   
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up JDK 11
+      uses: actions/setup-java@v3
+      with:
+        java-version: 11
+        cache: 'sbt'
+        distribution: 'temurin'
 
+    - name: Test with sbt
+      run: sbt test
+      working-directory: ${{env.EXERCISES_DIRECTORY}}/${{matrix.exercise}}
+  validate_course_summary:
+    if: ${{ always() }}
+    runs-on: ubuntu-latest
+    needs: validate_course
     steps:
+      - name: Check build matrix status
+        if: ${{ needs.validate_course.result != 'success' }}
+        run: exit 1
 
-      - name: Checkout Course Repo
-        uses: actions/checkout@v2
-        with:
-          path: course-repo
-          # fetch-depth: 0 indicates all history. (CMT requires them)
-          fetch-depth: 0
-        
-      - name: Setup Course Management Tools
-        uses: robinraju/release-downloader@v1.1
-        with:
-          repository: eloots/course-management-tools
-          tag: "1.0.0"
-          fileName: "course-management-tools.zip"
-          out-file-path: "."
-      - run: |
-          unzip course-management-tools.zip
-          echo "$GITHUB_WORKSPACE/course-management-tools/bin" >> $GITHUB_PATH
-      
-      - name: Set up JDK 11
-        uses: actions/setup-java@v1
-        with:
-          java-version: 11
-      
-      - name: Setup Coursier Cache
-        uses: coursier/cache-action@v6.2
-        with:
-          root: "course-repo"
-      
-      - name: Generate Tests Script using CMT
-        run: |
-          git config --global user.email "no-reply@lunatech.com"
-          git config --global user.name "Lunatech Labs"
-          cmt-mainadm -dot -t runTests.sh $GITHUB_WORKSPACE/course-repo
-     
-      - name: Run Tests
-        run: |
-          chmod +x runTests.sh          
-          ./runTests.sh
-          
   create_release:
     runs-on: ubuntu-latest
     needs: [validate_course]
@@ -61,7 +58,7 @@ jobs:
     steps:
 
       - name: Checkout Course Repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           path: lunatech-scala-2-to-scala3-course
           fetch-depth: 0          
@@ -78,9 +75,10 @@ jobs:
           echo "$GITHUB_WORKSPACE/course-management-tools/bin" >> $GITHUB_PATH
 
       - name: Set up JDK 11
-        uses: actions/setup-java@v1
+        uses: actions/setup-java@v3
         with:
           java-version: 11
+          distribution: 'temurin'
 
       - name: Setup Coursier Cache
         uses: coursier/cache-action@v6.2

README.md

@@ -1,42 +1,112 @@
 # Moving Forward from Scala 2 to Scala 3
 
-![Scala Course CI](https://github.com/lunatech-labs/lunatech-scala-2-to-scala3-course/workflows/Scala%20Course%20CI/badge.svg)
-
 ## Description
 
-The target audience for this course is the Scala _Application_ Developer Community.
-In other words, the focus is on people who use the language to develop 'end-user'
-applications and not necessarily those developers who design and write libraries,
-toolkits or frameworks (although they may benefit from what is in this course if
-they haven't already worked with Dotty).
+The target audience for this course is the Scala _Application_ Developer Community. In other words, the focus is on people who use the language to develop 'end-user' applications and not necessarily those developers who design and write libraries, toolkits or frameworks (although they may benefit from what is in this course if they haven't already worked with Scala 3).
 
-The goal of the course is to explore the new features in the Scala language brought
-by [the Dotty project](https://dotty.epfl.ch). Even though it is still early days
-and the first release candidate of the Scala 3 language is probably not out for
-another 6 months, it is our believe that one can never start too early to learn
-Dotty for the following reasons:
+The goal of the course is to explore the new features in the Scala language brought by [the Scala 3 project](https://dotty.epfl.ch). Even though it is still early days and the first release candidate of the Scala 3 language is probably not out for another 6 months, it is our believe that one can never start too early to learn Scala 3 for the following reasons:
 
 - There is a lot to learn, so if you wait until everything is ready, you risk having to play catchup.
-- There are many opportunities to contribute to the Dotty project, which will accelerate its development in the coming months. Using Dotty will provide opportunities to identity issues to be fixed sooner rather than later.
+- There are many opportunities to contribute to the Scala 3 project, which will accelerate its development in the coming months. Using Scala 3 will provide opportunities to identity issues to be fixed sooner rather than later.
+
+## Approach
+
+We start from an existing Scala 2 application: an [[Akka](https://akka.io)] actor based Sudoku solver. We start from the application as-is, but with an sbt build definition that uses the Scala 3 compiler.
+
+Through a series of exercises, we look at specific Scala 3 features and apply these to the Scala 2 code, thereby transforming it step-by-step into a version that exploits a whole series of nice features offered by the new language.
+
+Note that this is work in progress, so keep watching this space!
+
+## Usage
+
+This repository is structured in such a way that it can be transformed into two different artifacts for specific use cases:
+
+- A _studentified_ repository: this is a standalone sbt project which is typically used for teaching or learning purposes. A user of this repository will be working on one exercise at any one point in time and will be able to use a number of custom [sbt] commands:
+    - `man`: print a manual page for the global project
+    - `man e`: print a manual page for the current exercise. In general, this page will contain some background information on the exercise and a series of specific instructions, hints or tips for the current exercise
+    - `listExercises`: will print a list of all available exercises
+    - `nextExercise`: move to the next exercise and pull in the tests (if any) for that exercise. This command preserves the current state of the application leaving any code added or changed by the student unmodified.
+    - `prevExercise`: the opposite of the `nextExercise` command
+    - `pullSolution`: pulls in the reference solution code for the current exercise. This command is handy in a class room setting where at some point in time, the instructor wants to move to the next exercise and the student hasn't completed the current exercise. Note that it will overwrite any code written by the student
+    - `gotoExercise <exerciseID>`: jump to an exercise specified by the exerciseID. Note that this command support TAB completion for the exerciseID. Also, remember that this will pull in tests for the exercise and probably you'll want to pull in the solution by running the `pullSolution` command.
+    - `saveState`: can be executed prior to executing the `pullSolution` command: it will save the current state of an exercise so that it can be restored later.
+    - `savedStates`: show the exercise ids of all exercises for which a state was saved
+    - `restoreState <exerciseID>`: restore a previously save state
+- A _linearized_ repository: this is a git repository in which every exercise in the master repository is turned into a commit:
+  - Used to edit the master repository: In general this is a scratch pad repository that is discarded once it has served its purpose. In this use case, interactive rebasing on the linearized repo is used to transform the code across a range of exercises. Once this rebasing is finished, all applied changes can be applied on the master repo by a process of `delinearization`
+  - **There is a second use case for a linearized repo: it can can be used to inspect the differences between consecutive exercises (using a tools such as `SourceTree` or `GitKraken`)**
+
+_Studentification_, _linearization_, and _delinearization_ as well as some administrative tasks (such as renumbering exercises), is done using the so-called [Course Management Tools](https://github.com/lightbend/course-management-tools).
+
+In the following sections, we'll explain `studentify`, `linearize` and `delinearize` commands.
+
+### How to _"studentify"_ a master repository
+
+1. Create a folder in which the _studentified_ version will be
+- Clone the [Course Management Tools (CMT)](https://github.com/lightbend/course-management-tools)
+- Start an `sbt` session in the cloned CMT repo
+- From the `sbt` prompt, run the _studentify_ command with the `-dot` option and provide two arguments:
+    - The first one is the _absolute_ path to the root folder of the master repository of the exercises
+    - The second one is the _absolute_ path of the folder in which the studentified version will be created
+- Once the _studentify_ command is finished, you can _cd_ into the studentified versions root folder and start an _sbt_ session. You will now be able to use all the student commands listed in the previous section.
+
+Assuming that:
+
+- The root folder of the cloned course master repo is located at the following [absolute] path: `/home/userx/src/lunatech-scala-2-to-scala3-course`
+- The folder that will hold the _studentified_ version has the following [absolute] path: `/home/userx/stu`
+
+`studentify` should be invoked as follows:
+
+```
+studentify -dot /home/userx/src/lunatech-scala-2-to-scala3-course /home/userx/stu
+```
+
+### How to _"linearize"_/_"delinearize"_ a master repository
+
+In the context of the _"Moving from Scala 2 to Scala 3"_ course, _linearize_ allows one to view the changes between the different exercises. In other words, this feature allows one to see exactly what needs to be done to _"solve"_ the exercise. So, if you want to actually learn something, don't use this feature — instead, give the exercises a try first...
+
+In a broader context, _"linearize"_/_"delinearize"_ is an important tool to evolve/change the master repository of this course.
+
+The following picture shows the typical process to evolve code in a master repository with the utilisation of a _linearized_ repository:
 
-## The exercises master repository
+![Linearization/Delinearization](images/Lin-Delin.png)
 
-This repository, located in the `exercises` subfolder, contains all exercises in a multi-project _sbt_ build. In order to run exercises directly from this repo, _cd_ into this folder and run _sbt_. Alternatively, import the build.sbt file in your favourite development environment (Metals with a client of your choice or IntelliJ).
+Follow the following steps:
 
-## The snippets repository
+1. Choose a folder in which the _linearized_ version will be created
+- Clone the [Course Management Tools (CMT)](https://github.com/lightbend/course-management-tools)
+- Start an `sbt` session in the cloned CMT repo
+- Run the _linearize_ command and provide two arguments:
+    - The first one is the _absolute_ path to the root folder of the master repository of the exercises
+    - The second one is the absolute path of the folder in which the _linearized_ version will be created (see 1.)
+- Once the _linearize_ command is finished, _cd_ into the _linearized_ version's root folder and start refactoring your code using interactive rebasing (e.g. `git rebase -i --root`).
+- To apply all changes made in the _linearized_ repo to the master repository, execute the `delinearize` command supplying two arguments:
+  - The first one is the _absolute_ path to the root folder of the master repository of the exercises
+  - The second one is the absolute path of the `linearized` project folder
+- Repeat the _interactive rebasing_ / _delinearization_ sequence as many times as you want
 
-This repository, located in the `code-snippets` folder contains small examples, built mainly for demo purposes (and for inclusion in course slides).
+Assuming that:
 
-## Course Artifacts
+- The root folder of the cloned course master repo is located at the following [absolute] path: `/home/userx/src/lunatech-scala-2-to-scala3-course`
+- The folder that will hold the _linearized_ version has the following [absolute] path: `/home/userx/lin`
 
-Various artifacts are generated for this course:
+`linearize` should be invoked as follows:
 
-- The exercises in _studentified_ format: this is the format that is tuned for learning purposes.
-- The exercises in _linearized_ format: useful to study the changes between consecutive exercises.
-- The course slide deck in PDF format.
+```
+linearize -dot /home/userx/src/lunatech-scala-2-to-scala3-course /home/userx/stu
+```
 
-If you want to have a concise overview on how to utilize the _studentified_ and the _linearized_ artifacts, there's a video on this topic what you can find [here](https://youtu.be/2zmXTGG7Nkg).
+With the same assumptions, _delinearizing_ the linearized repo is done with the following command:
 
-You can find these artifacts in [the releases](https://github.com/lunatech-labs/lunatech-scala-2-to-scala3-course/releases) of this project.
+```
+delinearize /home/userx/src/lunatech-scala-2-to-scala3-course /home/userx/stu/lunatech-scala-2-to-scala3-course
+```
+Note two changes on this command compared to the `linearize` one: the `-dot` option is not present and the second argument is changed.
 
-> Note: We recently renamed the default branch to `main`. If you already have a clone/fork of this repo, please follow the instructions in the [0.24.0-v2 release notes](https://github.com/lunatech-labs/lunatech-scala-2-to-scala3-course/releases/tag/0.24.0-v2)
+> NOTES
+> 
+> - During the process of interactive rebasing, make sure NOT to change the commit message (which in fact is the exercise's project name) or to squash commits as this will make it impossible to _delinearize_ the project.
+> - Editing code directly in the _master repo_ and editing code via _linearize_/_delinearize_ are mutually exclusive processes. In practice, this means that when you've been using `linearize`/`delinearize` and you decide to make a change directly to files in the exercises in the master repository, you should discard the `linearized` artifact.
+> - Project `common` is aggregated in all exercises. As such, it is the same across _all_ exercises. Also, the _Linearization_/_Delinearization_ process will not transfer changes made in the _linearized_ repository
+> - `studentify` and `linearize` mandate that your master repository has no files in your git _index_ or _workspace_, so, commit any work before using these commands. Don't worry about commiting stuff temporarily. Either stash any pending changes or commit them and possibly squash them later.
+> Finally: reflect carefully about the best editing approach. In many cases, direct edits in the master repository may be simpler to apply than going through an interactive rebasing session.

course-management.conf

@@ -1,11 +1,27 @@
-studentify {
-	
-  relative-source-folder = exercises
+cmt {
+  # Folder in the main git repository holding the exercises
+  main-repo-exercise-folder = exercises
 
-  main-base-project-name = scala-2-to-scala-3-main
-  studentified-project-name = scala-2-to-scala-3
+  # Folder in studentified repo holding the current exercise code
+  studentified-repo-active-exercise-folder = code
 
-  use-configure-for-projects = true
+  # List of folders containing test code
+  test-code-folders = [
+    "src/test"
+  ]
 
-  readme-in-test-resources = false
+  # List of README files
+  read-me-files = [
+    "README.md"
+  ]
+
+  # List of files or folders to leave untouched in the studentified
+  # repo.
+  cmt-studentified-dont-touch = [
+    .idea
+    .bsp
+    .bloop
+    .vscode
+    target
+  ]
 }