From f7a79fcaf321d5ce6cf9abc0ee93e2459c270a8c Mon Sep 17 00:00:00 2001 From: Eric Loots Date: Fri, 10 Feb 2023 15:31:21 +0100 Subject: [PATCH] Update documentation and bump mdoc version (#205) * Update documentation and bump mdoc version - Bump `mdoc` version - Update documentation to reflect the last changes - Update command references to reflect the modified command line options for `cmta` and `cmtc` - Add new functionallity - `cmtc set-current-course` command - check if test code has been modified when doing a `next-exercise`, `previous-exercise`, `goto-exercise`, and `goto-first-exercise` * cmta option change - `cmta` short option names `-s` and `-l` changed to `-d` * Formatting --- docs/getting_started.md | 18 +++--- docs/reference-cmta.md | 87 +++++++++++++++++++---------- docs/reference-cmtc.md | 114 +++++++++++++++++++++++++++++++++----- docs/reference-config.md | 28 ---------- docs/reference-intro.md | 6 +- docs/workflows.md | 115 +++++++++++++++++++++------------------ project/plugins.sbt | 2 +- 7 files changed, 234 insertions(+), 136 deletions(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index 19fd09b9..85f38d04 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -19,28 +19,28 @@ Before describing the principle behind the tooling, we will start with having a ### The naive approach to CMT -When faced with the problem of maintaining a series of exercises, one approach applied by people who are familiar with version control software such as git, is to maintain the exercises as a series of commits in a git repository. +When faced with the problem of maintaining a series of exercises, one approach applied by people who are familiar with version control software such as **_git_**, is to maintain the exercises as a series of commits in a **_git_** repository. -Imagine we have a 16-exercise course —let's label it as version 1.0— in a git repository as depicted here: +Imagine we have a 16-exercise course —let's label it as version 1.0— in a **_git_** repository as depicted here: ![The Naive Approach 1](https://imgur.com/1aNEEgu.png) -Nice, but suppose we want now want to create version 1.1 of the course in which exercise 5 is changed. Applying the change can be done with git's interactive rebasing. The change in exercise 5 will ripple through the consecutive exercises (potentially resulting in some merge conflicts which we will have to resolve). After the edit process is finished, we end up with a git repository with a rewritten history. The before and after situation is as follows: +Nice, but suppose we want now want to create version 1.1 of the course in which exercise 5 is changed. Applying the change can be done with **_git_**'s interactive rebasing. The change in exercise 5 will ripple through the consecutive exercises (potentially resulting in some merge conflicts which we will have to resolve). After the edit process is finished, we end up with a **_git_** repository with a rewritten history. The before and after situation is as follows: ![The Naive Approach 2](https://imgur.com/b8eJUkC.png) So, we've achieved our goal, which was to change exercise 5, however, there are a number of problems with this approach and a number of questions that are rather difficult to answer... -- We've had to rewrite the git history. As a result, if the repo is on Github, we'll have to force push the change, effectively destroying version 1.0. At best, we can, before force pushing version 1.0, 'park' version 1.0 on a dedicated branch. Not very useful. +- We've had to rewrite the **_git_** history. As a result, if the repo is on Github, we'll have to force push the change, effectively destroying version 1.0. At best, we can, before force pushing version 1.0, 'park' version 1.0 on a dedicated branch. Not very useful. - Any open Pull Request on version 1.0 becomes detached and of little use on the current 1.1 version of the course. This is bad for collaboration. -- Having to use git interactive basing for _all_ updating tasks can be awkward in some cases. For example, each exercise may have a README file, and all these files in a course are uncorrelated. So, updating a README file in one exercise will result in a merge conflict in the rebasing process. Not a big deal, but rather inconvenient. +- Having to use **_git_** interactive basing for _all_ updating tasks can be awkward in some cases. For example, each exercise may have a README file, and all these files in a course are uncorrelated. So, updating a README file in one exercise will result in a merge conflict in the rebasing process. Not a big deal, but rather inconvenient. - What do we give users of the training course? This question actually leads to a series of other questions: - Do we want to hand the students the solution for each exercise? The answer is probably no in most cases. - After having completed an exercise, students should be able to move to the next exercise by "pulling" in the exercise instructions and possibly the tests for that exercise. How can we do that? - In the case of instructor-led courses, one will often run into the situation where some students haven't managed to complete an exercise in the allotted time. In that case, these students should be able to save the state of the exercise as-is and get the reference solution so that they can continue with the remainder of the exercises. - Students should be able to restore a previously saved state of an exercise. -In summary, the naive approach clearly is just a part of a larger puzzle. Let's now have a look at the CMT approach and see how it tackles the issues we highlighted. +In summary, the naive approach clearly is just part of a larger puzzle. Let's now have a look at the CMT approach and see how it tackles the issues we highlighted. ## The CMT approach @@ -48,13 +48,13 @@ A key characteristic of the CMT approach is that it adds the possibility to trac It makes this tracking in the second dimension possible by taking an unusual first step: it introduces the so-called _main repository_ from which, by means of one of the CMT tools, a number of artefacts can be derived for specific use cases. -In essence, the _main repository_ has a simple structure. It is a git repository, containing a CMT configuration file in the root folder, and a folder that holds all exercises in the course. In turn, the exercises are folders, one per exercise. +In essence, the _main repository_ has a simple structure. It is a **_git_** repository, containing a CMT configuration file in the root folder, and a folder that holds all exercises in the course. In turn, the exercises are folders, one per exercise. The following rules apply to the exercise folders: - Each exercise folder holds the complete state of the exercise. As such, CMT doesn't really care about its structure. _CMT is neither concerned about build tools, nor programming languages used in exercises_. - Exercise folder names have to follow a simple naming convention: `prefix_ddd_description`, where `ddd` is a 3 digit exercise number. -- Versioning of a course as a whole is done using regular git commits. +- Versioning of a course as a whole is done using regular **_git_** commits. - Exercises can be edited by modifying individual files directly without having to resort to interactive rebasing. This is very convenient in the case of exercise README files. Of course, the attentive reader will note that the ability to change exercise content via interactive rebasing as described in the naive approach is still highly desirable, and they are absolutely right. @@ -65,7 +65,7 @@ Let's have a look at how CMT tackles the issues and questions raised above one b ## Changing the content via interactive rebasing -Obviously, using interactive rebasing to change exercises can't be used directly on the _main repository_. For that reason, the tooling can create what is called a _linearised_ version of the _main repository_ in which each exercise is a commit in a git repository. Interactive rebasing can be used to change one or multiple exercises. After successfully completing the rebase process, the changes can be reflected back into the _main repository_ by a process called _delinearisation_. +Obviously, using interactive rebasing to change exercises can't be used directly on the _main repository_. For that reason, the tooling can create what is called a _linearised_ version of the _main repository_ in which each exercise is a commit in a **_git_** repository. Interactive rebasing can be used to change one or multiple exercises. After successfully completing the rebase process, the changes can be reflected back into the _main repository_ by a process called _delinearisation_. After completing this editing process, the _linearised_ artefact can be discarded. diff --git a/docs/reference-cmta.md b/docs/reference-cmta.md index 953e451c..02edad2e 100644 --- a/docs/reference-cmta.md +++ b/docs/reference-cmta.md @@ -5,24 +5,27 @@ sidebar_label: cmta --- ## Command Summary -`cmta` takes a command as the first parameters and it operates on a CMT main repository. +`cmta` takes a command as the first parameters and it operates on a CMT main [**_git_**] repository. The available commands and their function is as follows: -- [`studentify`](#cmta-studentify): generate a studentified artifact -- [`linearize `](#cmta-linearize): generate a linearized artifact -- [`delinearize`](#cmta-delinearize): reflect the changes made in a linearized artifact back into the corresponding main repository -- [`renum `](#cmta-renum): renumber exercises in a main repository -- [`dib `](#cmta-dib): duplicate a selected exercise in a main repository and insert it before that exercise +- [`studentify `](#cmta-studentify): generate a studentified artifact +- [`linearize `](#cmta-linearize): generate a linearized artifact +- [`delinearize `](#cmta-delinearize): reflect the changes made in a linearized artifact back into the corresponding main repository +- [`renumber-exercises `](#cmta-renumber-exercises): renumber exercises in a main repository +- [`duplicate-insert-before`](#cmta-duplicate-insert-before): duplicate a selected exercise in a main repository and insert it before that exercise The remainder of this section describes these commands in further detail. +> Note that all `cmta` commands require the CMT main repository to be clean +> from a **_git_** repository perspective which means that there should be no files +> in the repository's **_git_** workspace or index. ### cmta studentify #### Synopsys -` cmta studentify [-fg]
` +` cmta studentify [-fgh] -m
-d [-c ]` #### Description @@ -32,29 +35,33 @@ exercise. It can be distributed to users, in general people following a course, navigate between exercises, "pull" an exercise solution, save the current state of their work for a given exercise with the possibility to restore it at a later time. -> Note: `cmta studentify` will generate an error is the CMT main repository's git workspace isn't clean. +> Note: `cmta studentify` will generate an error is the CMT main repository's **_git_** workspace isn't clean. > So, commit any unsaved work before trying to studentify a repository. The following options are available:     **-f**: Force-delete a pre-existing studentified artifact. -    **-g**: Initialise the studentified artifact as a git repository. +    **-g**: Initialise the studentified artifact as a **_git_** repository. 
           This option can be useful in some use cases. For example, students may
           commit specific exercise state in git, then move to the next exercise
           and then use `git diff` to explore any changed test code.
+    **-c**: Specify an alternative CMT configuration file. + +    **-h**: Print command-specific help. + ### cmta linearize #### Synopsys -` cmta linearize [-f]
` +` cmta linearize [-fh] -m
-d [-c ]` #### Description -Generate a linearized artifact from a CMT main repository. The former is a git repository in which +Generate a linearized artifact from a CMT main repository. The former is a **_git_** repository in which each commit corresponds to the state of an exercise of the main repository. The first (oldest) commit in the repo corresponds to the first exercise in the main repository. The commit message for each commit is a single line with the name of the exercise in it. @@ -68,7 +75,11 @@ The following options are available:     **-f**: Force-delete a pre-existing studentified artifact. -> Note: `cmta linearize` will generate an error is the CMT main repository's git workspace isn't clean. +    **-c**: Specify an alternative CMT configuration file. + +    **-h**: Print command-specific help. + +> Note: `cmta linearize` will generate an error is the CMT main repository's **_git_** workspace isn't clean. > So, commit any unsaved work before trying to linearize a repository. > Warning: It is important to leave the commit messages in the linearized repository as-is. Also @@ -79,7 +90,7 @@ The following options are available: #### Synopsys -` cmta delinearize
` +` cmta delinearize [-h] -m
-d [-c ]` #### Description @@ -87,33 +98,45 @@ Apply the state of a linearized repository to its corresponding main repository. its task, the delinearization command will check that the linearized repository and the main repository "match", i.e. they should have the same number of exercises, with matching exercise names. -### cmta dib +The following options are available: + +    **-c**: Specify an alternative CMT configuration file. + +    **-h**: Print command-specific help. + +### cmta duplicate-insert-before #### Synopsys -` cmta dib -n
` +` cmta duplicate-insert-before [-h] -n -m
[-c ]` #### Description -> Note: **_dib_** is an acronym for **_d_**uplicate [and] **_i_**nsert **_b_**efore. -The exercise number (N), passed in via the -n parameter, will be duplicated and inserted as a new exercise -before the exercise with that number. +The exercise number (N), passed in via the -n parameter, will be duplicated and +inserted as a new exercise before the exercise with that number. It there is a gap before the original exercise in the exercise -series, the duplicated exercise will have sequence number N - 1. Otherwise, room will be made for the -duplicated exercise by shifting exercises around. Note that if the exercises after the insertion point -have one or more gaps in the numbering, those gaps will be removed and the exercises will be renumbered as a -continuous series. +series, the duplicated exercise will have sequence number N - 1. +Otherwise, room will be made for the duplicated exercise by shifting +exercises around. Note that if the exercises after the insertion point +have one or more gaps in the numbering, those gaps will be removed and +the exercises will be renumbered as a continuous series. + +In general, the description of the new, duplicated exercise will be what +it was followed by __copy_. + +The following option are available: + +    **-c**: Specify an alternative CMT configuration file. -In general, the description of the new, duplicated exercise will be what it was followed -by __copy_. +    **-h**: Print command-specific help. -### cmta renum +### cmta renumber-exercises #### Synopsys -` cmta renum [--from ,--to ,--step ]
` +` cmta renumber-exercises [-f ,-t , -s , -h] -m
[-c ]` #### Description @@ -126,22 +149,26 @@ numbers are incremented between consecutive exercises. The following options are available: -    **--from**: number of the exercise at which the renumbering needs to be started. +    **-f**: number of the exercise at which the renumbering needs to be started. 
           This option enables partial renumbering of the exercise set. The value passed as an
           argument to this option is the number of the exercise at which the renumbering should
           start. All subsequent exercises, if any, will be renumbered.
-    **--to**: move the exercise pointed-to by **--from** to this **--to** offset. +    **-t**: move the exercise pointed-to by **--from** to this **--to** offset. 
           This option allows moving a subset of the exercises to a new point (offset). As such, it
           can created gaps in the exercise numbering.
-    **--step**: defines the increment between subsequent, renumbered exercises. +    **-s**: defines the increment between subsequent, renumbered exercises. 
.
           By default, this value is 1, so renumbered exercises will have numbers that are contiguous.
           Using a value different than 1 will introduce gaps in the numbering between consecutive
           exercises
-
\ No newline at end of file + + +    **-c**: Specify an alternative CMT configuration file. + +    **-h**: Print command-specific help. \ No newline at end of file diff --git a/docs/reference-cmtc.md b/docs/reference-cmtc.md index 637e2264..c4861303 100644 --- a/docs/reference-cmtc.md +++ b/docs/reference-cmtc.md @@ -9,8 +9,15 @@ sidebar_label: cmtc `cmtc` takes a command as the first parameters and it operates on a studentified CMT main repository. +As the `cmtc` command operates on a studentified repository, this repository can +be passed via the `-s` option. As this becomes rather laborious after a while, +it can be set as a default for subsequent invocations of `cmtc` with the +`cmtc set-current-course` command. Note that this will 'persist' this setting +in the users home folder in the following location: `~/.cmt/cmt.conf`. + The available commands and their function is as follows: +- [`set-current-course`](#cmtc-set-current-course): set the location of the current course - [`list-exercises`](#cmtc-list-exercises): list exercises - [`next-exercise`](#cmtc-next-exercise): go to the exercise after the current one - [`previous-exercise`](#cmtc-previous-exercise): go to the exercise before the current one @@ -24,11 +31,26 @@ The available commands and their function is as follows: The remainder of this section describes these commands in further detail. +### cmtc set-current-course + +#### Synopsys + +`cmtc set-current-course [-h] -s ` + +#### Description + +Set the location of the current course making it the default for subsequent +invocations of other `cmtc` commands. + +The following option is available: + +    **-h**: Print command-specific help. + ### cmtc list-exercises #### Synopsys -`cmtc list-exercises ` +`cmtc list-exercises [-h] -s ` #### Description @@ -59,11 +81,15 @@ This output shows that there are 16 exercises in the repo. It also show their corresponding exercise IDs. We also see that the current active exercise is `exercise_003_qute_products`. +The following option is available: + +    **-h**: Print command-specific help. + ### cmtc next-exercise #### Synopsys -`cmtc next-exercise ` +`cmtc next-exercise [-hf] -s ` #### Description @@ -76,15 +102,24 @@ After finishing an exercise successfully (by making all tests pass), the student the `cmtc next-exercise` command, which pulls in the instructions and tests for the next exercise and the exercise solving process can continue. -> Warning: this command will overwrite any modification that a student has made to tests. +> Note: this command will check if any modifications have been made to test code files. +> If changes are detected, the execution of the command is aborted and an error message +> is printed that lists the modified files. The student can then decided to either force +> the move using the `-f` option, or to move the changed file(s) to a new location. > Any custom tests have to be saved in a location that is not part of the configured > set of test code folders (see setting [`cmt.test-code-folders`](reference-config.md#test-code-folders)) +The following options are available: + +    **-f**: Force moving to the next exercise. + +    **-h**: Print command-specific help. + ### cmtc previous-exercise #### Synopsys -`cmtc previous-exercise ` +`cmtc previous-exercise [-hf] -s ` #### Description @@ -93,11 +128,22 @@ previous exercise. Which files are pulled in is defined in settings [`cmt.test-code-folders`](reference-config.md#test-code-folders) and [`cmt.read-me-files`](reference-config.md#read-me-files). All other files are left as-is. +> Note: this command will check if any modifications have been made to test code files. +> If changes are detected, the execution of the command is aborted and an error message +> is printed that lists the modified files. The student can then decided to either force +> the move using the `-f` option, or to move the changed file(s) to a new location. + +The following options are available: + +    **-f**: Force moving to the previous exercise. + +    **-h**: Print command-specific help. + ### cmtc pull-solution #### Synopsys -`cmtc pull-solution ` +`cmtc pull-solution [-h] -s ` #### Description @@ -109,13 +155,17 @@ They can do so by executing the `cmtc save-state` command before executing `cmtc Any saved state can be restored later by means of the `cmtc restore-state` command. `cmtc pull-solution` will pull _all_ files for the current exercise. As a result, all code present -in the source code folder will be overwritten. +in the source code folder will be overwritten. + +The following option is available: + +    **-h**: Print command-specific help. ### cmtc pull-template #### Synopsys -`cmtc pull-template