You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Mar 27, 2025. It is now read-only.
Copy file name to clipboardExpand all lines: README.md
+58-63Lines changed: 58 additions & 63 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,92 +21,87 @@ Note that this is work in progress, so keep watching this space!
21
21
22
22
This repository is structured in such a way that it can be transformed into two different artifacts for specific use cases:
23
23
24
-
- 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:
25
-
-`man`: print a manual page for the global project
26
-
-`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
27
-
-`listExercises`: will print a list of all available exercises
28
-
-`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.
29
-
-`prevExercise`: the opposite of the `nextExercise` command
30
-
-`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
31
-
-`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.
32
-
-`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.
33
-
-`savedStates`: show the exercise ids of all exercises for which a state was saved
34
-
-`restoreState <exerciseID>`: restore a previously save state
35
-
- A _linearized_ repository: this is a git repository in which every exercise in the master repository is turned into a commit:
36
-
- 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`
37
-
-**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`)**
24
+
- 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 commands via the `cmtc` cli:
25
+
26
+
-`cmtc list-exercises`: will print a list of all available exercises. The current exercise is marked with a **_*_**.
27
+
-`cmtc next-exercise`: move to the next exercise and pull in the tests (if any) and exercise instructions for that exercise. This command preserves the current state of the application leaving any code added or changed by the student unmodified.
28
+
-`cmtc previous-exercise`: the opposite of the `next-exercise` command.
29
+
-`cmtc pull-solution`: 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. Before pulling the exercise
30
+
solution, the student can save the current state of their work with the `cmtc save-state` command.
31
+
-`cmtc goto-exercise <exerciseID>`: jump to an exercise specified by the exerciseID.
32
+
Remember that this will pull in tests for the exercise and probably you'll want to
33
+
pull in the solution by running the `pullSolution` command.
34
+
-`cmtc save-state`: can be executed prior to executing the `cmtc pull-solution`
35
+
command: it will save the current state of an exercise so that it can be restored
36
+
later.
37
+
-`cmtc list-saved-states`: show the exercise ids of all exercises for which a
38
+
state was saved.
39
+
-`cmtc restore-state <exerciseID>`: restore a previously save exercise state.
40
+
41
+
- A _linearized_ repository: this is a git repository in which every exercise in the
42
+
master repository is turned into a commit:
43
+
- Used to edit the master repository: In general this is a scratch pad repository that
44
+
is discarded once it has served its purpose. In this use case, interactive rebasing
45
+
on the linearized repo is used to transform the code across a range of exercises.
46
+
Once this rebasing is finished, all applied changes can be applied on the master
47
+
repo by a process of `delinearization`
48
+
-_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`)_
38
49
39
50
_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).
40
51
41
52
In the following sections, we'll explain `studentify`, `linearize` and `delinearize` commands.
42
53
43
54
### How to _"studentify"_ a master repository
44
55
45
-
1. Create a folder in which the _studentified_ version will be
46
-
- Clone the [Course Management Tools (CMT)](https://github.com/lightbend/course-management-tools)
47
-
- Start an `sbt` session in the cloned CMT repo
48
-
- From the `sbt` prompt, run the _studentify_ command with the `-dot` option and provide two arguments:
49
-
- The first one is the _absolute_ path to the root folder of the master repository of the exercises
50
-
- The second one is the _absolute_ path of the folder in which the studentified version will be created
51
-
- 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.
56
+
#### Clone the main repo
52
57
53
-
Assuming that:
58
+
Clone this repo (aka the main repo for this course) to your computer:
54
59
55
-
- 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`
56
-
- The folder that will hold the _studentified_ version has the following [absolute] path: `/home/userx/stu`
#### Create a folder that will hold the studentified repo
73
+
74
+
Create a folder in which the _studentified_ version will be created. For example:
75
+
76
+
```bash
77
+
$ mkdir ~/tmp/stu
62
78
```
63
79
64
-
###How to _"linearize"_/_"delinearize"_ a master repository
80
+
#### Generate the studentified repo using `cmta`
65
81
66
-
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...
82
+
Run the `cmta` command to _studentify_the main repo:
67
83
68
-
In a broader context, _"linearize"_/_"delinearize"_ is an important tool to evolve/change the master repository of this course.
drwxr-xr-x@ 10 ericloots staff 320 10 Mar 13:23 code
91
+
```
73
92
74
-
Follow the following steps:
93
+
The `code` folder holds the exercise source code as an sbt project.
75
94
76
-
1. Choose a folder in which the _linearized_ version will be created
77
-
- Clone the [Course Management Tools (CMT)](https://github.com/lightbend/course-management-tools)
78
-
- Start an `sbt` session in the cloned CMT repo
79
-
- Run the _linearize_ command and provide two arguments:
80
-
- The first one is the _absolute_ path to the root folder of the master repository of the exercises
81
-
- The second one is the absolute path of the folder in which the _linearized_ version will be created (see 1.)
82
-
- 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`).
83
-
- To apply all changes made in the _linearized_ repo to the master repository, execute the `delinearize` command supplying two arguments:
84
-
- The first one is the _absolute_ path to the root folder of the master repository of the exercises
85
-
- The second one is the absolute path of the `linearized` project folder
86
-
- Repeat the _interactive rebasing_ / _delinearization_ sequence as many times as you want
95
+
## Where can I find the `cmta` and `cmtc` tools?
87
96
88
-
Assuming that:
97
+
These are located in the `CMT-tools` folder in the root of this repo.
89
98
90
-
- 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`
91
-
- The folder that will hold the _linearized_ version has the following [absolute] path: `/home/userx/lin`
99
+
Copy them to a suitable folder on your system and make sure that this folder is on
100
+
your PATH (for windows users, copy both the `.bat` files too.
Note two changes on this command compared to the `linearize` one: the `-dot` option is not present and the second argument is changed.
105
-
106
-
> NOTES
107
-
>
108
-
> - 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.
109
-
> - 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.
110
-
> - 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
111
-
> -`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.
112
-
> 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.
0 commit comments