diff --git a/Themis.xcodeproj/project.pbxproj b/Themis.xcodeproj/project.pbxproj index 637e00e8..37d49747 100644 --- a/Themis.xcodeproj/project.pbxproj +++ b/Themis.xcodeproj/project.pbxproj @@ -199,7 +199,6 @@ E536EAD1297458240078E077 /* SwiftUIReorderableForEach in Frameworks */ = {isa = PBXBuildFile; productRef = E536EAD0297458240078E077 /* SwiftUIReorderableForEach */; }; E536EAD3298C00380078E077 /* DateTimelineView.swift in Sources */ = {isa = PBXBuildFile; fileRef = E536EAD2298C00380078E077 /* DateTimelineView.swift */; }; E58C68062935037C008E6FEE /* EditFeedbackViewBase.swift in Sources */ = {isa = PBXBuildFile; fileRef = E58C68052935037C008E6FEE /* EditFeedbackViewBase.swift */; }; - F9032CA5294A159700B2DED5 /* CachedAsyncImage in Frameworks */ = {isa = PBXBuildFile; productRef = F9032CA4294A159700B2DED5 /* CachedAsyncImage */; }; F922443A297BFD1A008E4374 /* CircularProgressView.swift in Sources */ = {isa = PBXBuildFile; fileRef = F9224439297BFD1A008E4374 /* CircularProgressView.swift */; }; F958C4DE29887DE800E70669 /* ShakeEffect.swift in Sources */ = {isa = PBXBuildFile; fileRef = F958C4DD29887DE800E70669 /* ShakeEffect.swift */; }; /* End PBXBuildFile section */ @@ -426,7 +425,6 @@ E536EAD1297458240078E077 /* SwiftUIReorderableForEach in Frameworks */, 657534B22A0F7A52004B0C3F /* DesignLibrary in Frameworks */, 657534AC2A0F7A52004B0C3F /* Account in Frameworks */, - F9032CA5294A159700B2DED5 /* CachedAsyncImage in Frameworks */, 6564DC0E2A00EFFC00CF2F89 /* SharedModels in Frameworks */, 06A99D3F2A94D99000E48066 /* Starscream in Frameworks */, ); @@ -1181,7 +1179,6 @@ name = Themis; packageProductDependencies = ( E2192EE0291E6F780092CE58 /* KeychainAccess */, - F9032CA4294A159700B2DED5 /* CachedAsyncImage */, E2E3852929437F9100F5854D /* CodeEditor */, E536EAD0297458240078E077 /* SwiftUIReorderableForEach */, 657534A92A0F7A52004B0C3F /* APIClient */, @@ -1271,7 +1268,6 @@ mainGroup = 83396D2129155934003EF727; packageReferences = ( E2192EDF291E6F780092CE58 /* XCRemoteSwiftPackageReference "KeychainAccess" */, - F9032CA3294A159700B2DED5 /* XCRemoteSwiftPackageReference "swiftui-cached-async-image" */, E2E3852829437F9100F5854D /* XCRemoteSwiftPackageReference "CodeEditor" */, E536EACF297458240078E077 /* XCRemoteSwiftPackageReference "swiftui-reorderable-foreach" */, 657534A82A0F7A52004B0C3F /* XCRemoteSwiftPackageReference "artemis-ios-core-modules" */, @@ -1903,14 +1899,6 @@ kind = branch; }; }; - F9032CA3294A159700B2DED5 /* XCRemoteSwiftPackageReference "swiftui-cached-async-image" */ = { - isa = XCRemoteSwiftPackageReference; - repositoryURL = "https://github.com/lorenzofiamingo/swiftui-cached-async-image"; - requirement = { - kind = upToNextMajorVersion; - minimumVersion = 2.0.0; - }; - }; /* End XCRemoteSwiftPackageReference section */ /* Begin XCSwiftPackageProductDependency section */ @@ -1999,11 +1987,6 @@ package = E536EACF297458240078E077 /* XCRemoteSwiftPackageReference "swiftui-reorderable-foreach" */; productName = SwiftUIReorderableForEach; }; - F9032CA4294A159700B2DED5 /* CachedAsyncImage */ = { - isa = XCSwiftPackageProductDependency; - package = F9032CA3294A159700B2DED5 /* XCRemoteSwiftPackageReference "swiftui-cached-async-image" */; - productName = CachedAsyncImage; - }; /* End XCSwiftPackageProductDependency section */ }; rootObject = 83396D2229155934003EF727 /* Project object */; diff --git a/docs/admin/app/infrastructure.rst b/docs/admin/app/infrastructure.rst index dec69936..58166f85 100644 --- a/docs/admin/app/infrastructure.rst +++ b/docs/admin/app/infrastructure.rst @@ -1,10 +1,19 @@ Infrastructure Setup =========================================== -.. Describe the setup of the infrastructure in terms of hardware, software and protocols so it can be configured by a system administrator at the client site. This include virtual machines, software packages etc. You can reuse the deployment diagram from the section Hardware/Software Mapping. Describe the installation and startup order for each component. You can reuse the use cases from the section Boundary Conditions. For example: If you have used docker reuse the Docker installation instructions from the cross project space. +.. Describe the setup of the infrastructure in terms of hardware, software and protocols so it can be configured by a +.. system administrator at the client site. This include virtual machines, software packages etc. You can reuse the +.. deployment diagram from the section Hardware/Software Mapping. Describe the installation and startup order for each +.. component. You can reuse the use cases from the section Boundary Conditions. For example: If you have used docker +.. reuse the Docker installation instructions from the cross project space. + +Themis needs to connect to an Artemis server instance to operate. The deployment diagram below can be useful to +understand the infrastructure: + +.. image:: /contributor/system-design/images/deployment_diagram.png The app can be installed on iPads via `TestFlight`_. Therefore, it requires TestFlight to be installed on the iPad and the user -to be part of at least one group, either via Apple-ID or via public TestFlight link. The only formal requirement is iPadOS 16. +to be part of at least one group, either via Apple-ID or via public TestFlight link. The only formal requirement is iPadOS 17. Apart from that, the iPad app can also be tested via XCode and its integrated Simulator. To prevent entering the Artemis credentials every time rebuilding the app while testing, just add them to your XCode environment variables. For that, click on diff --git a/docs/admin/app/third-party.rst b/docs/admin/app/third-party.rst index 382e10ff..caa4a0f4 100644 --- a/docs/admin/app/third-party.rst +++ b/docs/admin/app/third-party.rst @@ -7,6 +7,13 @@ Introduction The Themis iPad App utilizes a number of open-source libraries to enhance its functionality and provide a seamless user experience. This provides an overview of the libraries used in the Themis iPad App. +ArtemisCore +----------- +The ArtemisCore library contains components that are common to all Artemis-related iOS clients. +Themis depends on this library for authentication, service layer calls, models, and some shared UI elements. + +Library repository: https://github.com/ls1intum/artemis-ios-core-modules + KeychainAccess -------------- @@ -16,21 +23,13 @@ KeychainAccess provides a simple and secure way to store data in the iOS Keychai Library repository: https://github.com/kishikawakatsumi/KeychainAccess (master branch) - -SwiftUI-Cached-AsyncImage -------------------------- - -The SwiftUI-Cached-AsyncImage library provides an easy way to load and cache images asynchronously in SwiftUI. -This library is used in the Themis iPad App to display UML-Diagrams in a fast and efficient manner. - -Library repository: https://github.com/lorenzofiamingo/swiftui-cached-async-image (2.1.1 - Next Major) - CodeEditor ---------- The CodeEditor library is a customizable and extensible code editor component for SwiftUI. The library is used in the Themis iPad App to provide a code editor for the user to read Code. -It was modified locally in order to select and give feedback in the Code Editor +It was modified locally in order to support inline feedback. It is also reused for performing +text exercise assessments. Library repository: https://github.com/ZeeZide/CodeEditor.git (locally modified) @@ -42,11 +41,9 @@ This library is used in the Themis iPad App to provide the user with the ability Library repository: https://github.com/globulus/swiftui-reorderable-foreach (main branch) +SwiftUI-Shimmer +------------------------- +SwiftUI-Shimmer is used for the implementation of skeleton loading. Views that are shown as +placeholders while loading content are animated using this library. -Swift-Markdown-ui ------------------ - -The Swift-Markdown-ui library is used to parse and display markdown content in a SwiftUI app. -This library is used in the Themis iPad App to display markdown content from Artemis in a clean and formatted manner. - -Library repository: https://github.com/gonzalezreal/swift-markdown-ui (2.0.0 - next major) +Library repository: https://github.com/markiv/SwiftUI-Shimmer \ No newline at end of file diff --git a/docs/admin/issues.rst b/docs/admin/issues.rst index 300bbd4f..aa2ecaba 100644 --- a/docs/admin/issues.rst +++ b/docs/admin/issues.rst @@ -1,5 +1,8 @@ Known Issues and Workarounds =========================================== +.. TODO: Remove once Athena is fully integrated +*The information below will be removed once feedback suggestions are completely integrated into +Artemis.* The feedback suggestion server ThemisML currently only works with Java projects. This should be easy to fix by creating an ANTLR grammar for every additional language to support and configuring the codeBERT similarity comparison accordingly. diff --git a/docs/admin/themisml/index.rst b/docs/admin/themisml/index.rst index c62ed3dc..6a0ba966 100644 --- a/docs/admin/themisml/index.rst +++ b/docs/admin/themisml/index.rst @@ -1,6 +1,9 @@ ThemisML =========================================== +.. TODO: Remove once Athena is fully integrated +.. note:: *This section will be removed once feedback suggestions are completely integrated into Artemis.* + .. toctree:: :includehidden: diff --git a/docs/analysis/analysis-object-model.rst b/docs/analysis/analysis-object-model.rst deleted file mode 100644 index 7a9e4210..00000000 --- a/docs/analysis/analysis-object-model.rst +++ /dev/null @@ -1,22 +0,0 @@ -Analysis Object Model -=========================================== - -The Analysis Object Model describe the static structure of the system by means of classes, attributes and associations. - -.. image:: ../images/class_diagram.png - - -The **Course** class refers to different university courses that use the Artemis web application. Each course has a title and a description and has multiple exercises with each exercise class containing attributes for the problem statement, the grading instructions, the score, etc. A course can be taken or worked for by multiple users. - -The **User** class refers to an Artemis user. This class is inherited by the **Student** class representing students that are enrolled in a course as well as by the **Tutor** class representing the tutors for the corresponding course. Each user may take part in multiple courses. A tutor has additional tutor rights in the respective course on Artemis. - -Each student can work on multiple exercise and submit the respective solutions. After receiving feedback the student may review the tutor's feedback. This is modeled by the **Submission** class. A specific submission belongs to one exercise and each exercise can have multiple student submissions. A tutor who is using the Themis iPad App to provide feedback to the students can search for a student's submission or request a random one. When assessing a submission the respective repository is locked. - -The structure of a submission is given as follows: A submission for programming exercises consists of a file tree that is modeled with by the **FileTree** class. This connection is modeled via aggregation. A file tree can consist of multiple directories, as modeled by the **Directory** class which, in return, can also contain multiple sub-directories. A directory contains multiple source files, which are represented by the **SourceFile** class. - -The **Assessment** class represents the assessment a tutor does for a specific submission. The tutor can submit the assessment after providing feedback or cancel it. A tutor may have multiple assessments for multiple submissions. - -The abstract **Feedback** class is the focus of this Analysis Object Model. It represents the feedback the tutor provides for each student submission. A feedback object has a feedback text and credits and can be updated or deleted afterwards. Themis supports multiple types of feedback, all inheriting from the abstract superclass. Each feedback belongs to one submission and each submission can contain multiple feedbacks. -**GeneralFeedback** refers to feedback that is, as the name implies, general and applies to the entire submission or file, whereas **InlineFeedback** is feedback that refers to a specific code line. The **AutomaticTestCaseFeedback** models the automatic test cases that are executed by Artemis. -The **FeedbackSuggestions** class represents the feedback computed by the **FeedbackModel** class, which implements the *computeCodeSimilarity()* method to generate the feedback suggestions. **FeedbackModel** computes **FeedbackSuggestion** objects and does not have any information about the **FeedbackSuggestion** objects once they have been created. -Both the inline feedback and the feedback suggestions reference the specific source file the feedback refers to. diff --git a/docs/analysis/dynamic-model.rst b/docs/analysis/dynamic-model.rst deleted file mode 100644 index 814903aa..00000000 --- a/docs/analysis/dynamic-model.rst +++ /dev/null @@ -1,60 +0,0 @@ -Dynamic Model -=========================================== - -This section focuses on the dynamic behavior of the system. UML activity diagrams are the most suitable way of representation for this purpose. - -Since it is crucial to show the dynamic behavior of both Themis iPad App as well as for the ThemisML Server, this section will be divided into two parts. - -*************** -Themis iPad App -*************** - -Answering Student Questions ---------------------------- - -.. image:: ../images/activity_diagram_1.png - -This activity diagram shows how the flow of answering a student question on a certain exercise e.g. during the lecture looks like. Assume that the tutor already opened the app and navigated to the corresponding lecture course. - -1. The tutor navigates to the specific exercise. -2. If there are no questions from any student, the tutor is done. Otherwise, the tutor searches for the student's submission. -3. Then, the tutor opens the submission in *read-mode*. -4. The tutor evaluates the question. If the question is not resolved, the tutor continues answering it. -5. If otherwise, the tutor is done. - - -Assessing Student Submissions ------------------------------ - -.. image:: ../images/activity_diagram_2.png - -This activity diagram shows the workflow of assessing student submissions in the app. Assume that the tutor already opened the app and navigated to the corresponding lecture course. - -1. The tutor navigates to the specific exercise. -2. If there are no open assessments left, the tutor is done. -3. If otherwise, the tutor starts the assessment of submissions. The tutor receives a random student submission in return. -4. The tutor reviews the source code and the executed tests. -5. If there are feedback suggestions available, the suggestions are generated and the tutor adds them to the feedback list. Otherwise, the tutor checks if feedback is necessary. -6. Afterwards, the tutor can add inline and general feedback to the feedback list. -7. If the tutor is not yet done with providing feedback, they can review the source code and tests again, eventually for other files as well. -8. After providing all necessary feedback, the tutor can submit the feedback and thus continue the assessment process. -9. If there are no more open assessments left, the tutor cancels the assessment mode and is done. - - -*************** -ThemisML Server -*************** - -Generating Feedback Suggestions -------------------------------- - -.. image:: ../images/activity_diagram_ml.png - -This activity diagram shows the process of generating feedback suggestions. - -1. First, the submissions are loaded from the Themis notification request. -2. Then, the function blocks of each submission are extracted. This results in a list of function blocks. -3. Afterwards the similarity scores between the extracted function blocks and the function blocks that are stored in the database are computed. -4. If the score of a function block is above a given threshold, the function block is added to the suggestions list. Otherwise, the new function block is stored in the database. -5. If the suggestion is accepted by the tutor, the corresponding function block is stored in the database. - diff --git a/docs/analysis/ui.rst b/docs/analysis/ui.rst deleted file mode 100644 index 6bbd129c..00000000 --- a/docs/analysis/ui.rst +++ /dev/null @@ -1,78 +0,0 @@ -User Interface -=========================================== - -.. something in general about the ui - -The user interface of Themis is designed to be as intuitive as possible. The main goal is to provide a simple and easy to use interface for tutors to assess programming exercises. - -Initial Mockups -*************** - -The high-fidelity mockups below show the initial design draft for Themis. They focus on the assessment view and display the main -workflow using the iPad app. The view is mainly divided into three parts horizontally, including a file tree sidebar, -the code viewer as well as a correction sidebar (from left to right). Within the code viewer, tutors can highlight -specific lines of code and provide feedback. After finishing the assessment, the tutor can submit the feedback and -either jump to the next submission or stop assessing. - -+-----------------------------------------------------------+----------------------------------------------------------------+ -| .. figure:: ../images/mockup_assessment.png | .. figure:: ../images/mockup_feedback.png | -| :alt: Deployment diagram of Themis | :alt: Deployment diagram of Themis | -| :width: 450 | :width: 450 | -| :align: center | :align: center | -| | | -| *Assessment view (highlighted code)* | *Assessment view (feedback)* | -+-----------------------------------------------------------+----------------------------------------------------------------+ -| .. figure:: ../images/mockup_submit.png | .. figure:: ../images/mockup_next-action.png | -| :alt: Deployment diagram of Themis | :alt: Deployment diagram of Themis | -| :width: 450 | :width: 450 | -| :align: center | :align: center | -| | | -| *Assessment view (submit)* | *Assessment view (next action)* | -+-----------------------------------------------------------+----------------------------------------------------------------+ - - -Current Design -************** - -The current design is shown below. Starting with the course view, the tutor sees all exercises a course contains as -well as the corresponding information. Within each exercise, general statistics about the exercise are provided alongside -with the open submissions. While assessing, the tutor can give feedback using correction guidelines. An overview of all -feedback is listed in the correction sidebar (right side). Before finishing the assessment, the tutor can either save or -submit the current feedback. - - -+-----------------------------------------------------------+----------------------------------------------------------------+ -| .. figure:: ../images/design_course.png | .. figure:: ../images/design_exercise.png | -| :alt: Deployment diagram of Themis | :alt: Deployment diagram of Themis | -| :width: 450 | :width: 450 | -| :align: center | :align: center | -| | | -| *Course view* | *Exercise view* | -+-----------------------------------------------------------+----------------------------------------------------------------+ - -+-----------------------------------------------------------+----------------------------------------------------------------+ -| .. figure:: ../images/design_assessment.png | .. figure:: ../images/design_feedback.png | -| :alt: Deployment diagram of Themis | :alt: Deployment diagram of Themis | -| :width: 450 | :width: 450 | -| :align: center | :align: center | -| | | -| *Assessment view* | *Assessment view (feedback)* | -+-----------------------------------------------------------+----------------------------------------------------------------+ - -+-----------------------------------------------------------+----------------------------------------------------------------+ -| .. figure:: ../images/design_guidelines.png | .. figure:: ../images/design_feedback-list.png | -| :alt: Deployment diagram of Themis | :alt: Deployment diagram of Themis | -| :width: 450 | :width: 450 | -| :align: center | :align: center | -| | | -| *Assessment view (correction guidelines)* | *Assessment view (feedback overview)* | -+-----------------------------------------------------------+----------------------------------------------------------------+ - -+-----------------------------------------------------------+----------------------------------------------------------------+ -| .. figure:: ../images/design_save.png | .. figure:: ../images/design_submit.png | -| :alt: Deployment diagram of Themis | :alt: Deployment diagram of Themis | -| :width: 450 | :width: 450 | -| :align: center | :align: center | -| | | -| *Assessment view (save)* | *Assessment view (submit)* | -+-----------------------------------------------------------+----------------------------------------------------------------+ diff --git a/docs/analysis/use-case-model.rst b/docs/analysis/use-case-model.rst deleted file mode 100644 index 73c83b13..00000000 --- a/docs/analysis/use-case-model.rst +++ /dev/null @@ -1,12 +0,0 @@ -Use Case Model -=========================================== - -This section describes the functional behavior of the system as seen by the user. For this, UML use case diagrams are very suitable and show the interaction between the user and the system. In this setting, there are two systems and two different actors. - -.. image:: ../images/use_case_diagram.png - - -Themis is the system the tutor interacts with. A tutors main use cases are searching for a student submission, requesting a random submission and providing feedback. -The *provide feedback* use case includes the *submit assessment* use case since it is not possible to provide the student with feedback without submitting the exercise previously. -As a tutor might provide the student with code specific or general feedback, the corresponding use cases inherit from the *provide feedback* use case. -Providing students with feedback also includes evaluating the automatic feedback suggestions. diff --git a/docs/backlog/backlog.rst b/docs/backlog/backlog.rst deleted file mode 100644 index ebe9590a..00000000 --- a/docs/backlog/backlog.rst +++ /dev/null @@ -1,54 +0,0 @@ -Product Backlog -=========================================== -The following is a highlight of the most significant backlog items that have been successfully integrated into our project. - -* Create app icon/name -* Implement REST API for communication with Artemis -* Implement authentication functionality for Artemis users - - - Use bearer token / cookie based authentication based on Artemis version -* Implement functionality to view and switch between the tutors courses -* Implement view that shows all exercises for a course and allows selecting them - - - Show a timeline indicating release-, submission- and assessment (due) dates -* Implement view that shows assessment statistics for a specific exercise -* Implement functionality to search for a specific student's submission -* Implement functionality to open a submission in read-only-mode -* Implement functionality to start the assessment of a randomly assigned submission -* Implement functionality to continue the assessment of a previously saved/submitted assessment -* Implement view that is used for the assessment workflow - - - Show an expandable file tree of the submissions repository that allows selecting files - - Show all opened files as dismissable / rearrangeable tabs above the code editor - - Show the source code of the selected file in a code editor - - + Apply dynamic syntax highlighting based on the file extension - + Show the student's changes as a diff - + Highlight all code-specific inline feedbacks - + Toggle feedback edit-mode when clicking on inline highlight - + Indicate available feedback suggestions with a lightbulb and blue line next to the related code segment - - Implement functionality to undo/redo assessment-related inputs - - Implement selection tool that allows to mark code segments for feedback with finger/Apple Pencil - - Implement functionality to change the font size - - Implement functionality to accept a feedback suggestion - - Implement sheet that allows to give feedback consisting of a text and credits ranging from -10 to 10 - - + Allow choosing from list of correction guidelines as templates for feedback - - Show the current relative score of the assessed submission - - Show an expandable correction sidebar that includes all assessment-related information - - + Show the problem statement with UML diagrams and test case information - + Show the instructor's correction guidelines - + Show all current feedbacks for this assessment (general, inline, automatic) - - * Implement functionality to give general feedbacks - * Implement functionality to edit/delete inline/general feedbacks - * Tapping on inline feedbacks results in showing the related code segment in the code editor - - Implement functionality to save the current progress of an assessment - - Implement functionality to submit the assessment - - Implement functionality to dismiss the assessment -* Setup server for ML functionality -* Notify ML server when submitting assessments -* Store function blocks with related feedback in database -* Implement similarity comparison for function blocks of submissions with stored blocks in database -* Connect app to ML server \ No newline at end of file diff --git a/docs/contributor/dev-process/development-process.rst b/docs/contributor/dev-process/development-process.rst new file mode 100644 index 00000000..f9c9bba9 --- /dev/null +++ b/docs/contributor/dev-process/development-process.rst @@ -0,0 +1,100 @@ +******************* +Development Process +******************* + +.. contents:: Contents + :local: + :depth: 1 + +Naming Conventions for GitHub Pull Requests +=========================================== + +1. The first term is a main feature of Themis and is using code highlighting, e.g. “``Programming Exercise``:”. + + 1. Possible feature tags are: ``Programming Exercise``, ``Text Exercise``, ``Modeling Exercises``, ``File Upload Exercise``, ``Exam Mode``, ``Assessment View``, ``Course View``, ``Exercise View``, ``Login``, ``Documentation``. + 2. If the change is not visible to end users, or it is a pure development or test improvement, we use the term “``Development``:”. + 3. Everything else belongs to the ``General`` category. + +2. The colon is not highlighted. + +3. After the colon, there should be a verbal form that is understandable by end users and non-technical persons. + + 1. The text should be short, non-capitalized (except the first word) and should include the most important keywords. Do not repeat the feature if it is possible. + 2. We generally distinguish between bugfixes (the verb “Fix”) and improvements (all kinds of verbs) in the release notes. This should be immediately clear from the title. + 3. Good examples: + + - ``Exercise View``: Allow users to cancel submissions + - ``Assessment View``: Fix an issue when clicking on the save button + + +Creating and Merging a Pull Request +======================================== + +Precondition +--------------------------------- + +* Check if the functionality already exists in the `ArtemisCore `_ dependency + + If it does not, consider whether the change would also be useful for other iOS clients. If yes, create the PR in + the ArtemisCore repository instead. + +* Limit yourself to one functionality per pull request. +* Split up your task in multiple branches & pull requests if necessary. +* `Commit Early, Commit Often, Perfect Later, Publish Once. `_ + +1. Start Implementation +----------------------------------------- + +* `Open a draft pull request. `_ This allows for code related questions and discussions. + +2. Complete the implementation +--------------------------------------------- + +* Explain the changes you made in the pull request description +* Add screenshots if the changes affect the UI +* Have a look at the changes to make sure that the changes are only the ones necessary. +* Make sure that the build and the SwiftLint GitHub actions are passing +* Mark the pull request as `ready for review. `_ + +3. Review +--------- + +Developer +^^^^^^^^^ +* Actively look for reviews. Do not just open the pull request and wait. + +Reviewer +^^^^^^^^ +* Verify that the new functionality is working as expected. +* Verify that related functionality is still working as expected. +* Check the changes to + * conform with the code style. + * make sure you can easily understand the code. + * make sure that (extensive) comments are present where deemed necessary. + * performance is reasonable (e.g. number of API calls). +* Submit your comments and status (👍 Approve or 👎 Request Changes) using GitHub. + * Explain what you did (test, review code) in the review comment. + +4. Respond to review +-------------------- + +Developer +^^^^^^^^^ +* Use the pull request to discuss comments or ask questions. +* Update your code where necessary. +* Revert to draft if the changes will take a while during which review is not needed/possible. +* Set back to ready for review afterwards. +* Notify the reviewer(s) once your revised version is ready for the next review. +* Comment on "inline comments" (e.g. "Done"). + +Reviewer +^^^^^^^^ +* Respond to questions raised by the reviewer. +* Mark conversations as resolved if the change is sufficient. + +Iterate steps 3 & 4 until ready for merge (all reviewers approve 👍) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +5. Merge +-------- +A project maintainer merges your changes into the ``develop`` branch. \ No newline at end of file diff --git a/docs/contributor/guidelines/guidelines.rst b/docs/contributor/guidelines/guidelines.rst new file mode 100644 index 00000000..43e18d43 --- /dev/null +++ b/docs/contributor/guidelines/guidelines.rst @@ -0,0 +1,50 @@ +**************************** +Coding and Design Guidelines +**************************** + +.. contents:: Contents + :local: + :depth: 1 + + +Folder Structure +=========================================== +The app is located under ``/Themis`` and the main folders are: + +* **Models** - structs that encapsulate the app's data +* **Views** - structs that are responsible for building the user interface +* **ViewModels** - classes that are observed by views and control what is shown to the user +* **Services** - structs that make API calls +* **Extensions** - structs that extend the behavior of various types +* **Styles** - view modifiers, button styles and other style-related reusable elements + +User Interface (UI) +=========================================== +General +------- +* Adhere to the Model-View-ViewModel (MVVM) pattern +* Do not implement business logic in Views. Move it to the ViewModels instead. + +Design Language +--------------- +When making UI changes, it's crucial to maintain a delicate equilibrium between the design aesthetics +of Artemis and Apple. The objective is to create a user-friendly system by keeping UI elements +consistent with Artemis and simultaneously adhering to +`Apple's Human Interface Guidelines `_. + +Symbols +------- +Prioritize SF Symbols in your design choices, and resort to custom assets sparingly, using them only +when it is really necessary. + +Loading State +------------- +Usually, JSON data is decoded into arrays of model elements. In such cases, use the ``.mock(if:)`` function in combination +with ``.showsSkeleton(if:)`` view modifier to generate mock data while the actual data is loading and show a skeleton animation +to convey the loading state to the user. If you are not satisfied with the effect of ``.showsSkeleton(if:)``, you can +create custom skeleton (placeholder) views and present them using the ``shows(_ skeletonView: , if:)`` view modifier. + +Reuse +=========================================== +Always keep in mind that any functionality or UI element that will be shared between Artemis iOS clients should be +implemented in the `ArtemisCore `_ package. diff --git a/docs/system/access-control.rst b/docs/contributor/system-design/access-control.rst similarity index 88% rename from docs/system/access-control.rst rename to docs/contributor/system-design/access-control.rst index 741d1e57..8b353594 100644 --- a/docs/system/access-control.rst +++ b/docs/contributor/system-design/access-control.rst @@ -1,19 +1,17 @@ .. _Access Control and Security: Access Control and Security -=========================================== +-------------------------- .. Access control and security describes the user model of the system in terms of an access matrix. This section also describes security issues, such as the selection of an authentication mechanism, the use of encryption, and the management of keys. This section is optional. It should be included if the non-functional requirements include security concerns. For details refer to section 7.4.3 in Prof. Bruegge's book. -*************** -Themis iPad App -*************** - In order to make requests to the Artemis server the user has to be authenticated, i.e. has to have a cookie which contains a jwt token. The corresponding cookie is set by the Artemis server when calling the `/authenticate`_ route. In iOS cookies are stored and managed in the ``HTTPCookieStorage``, which means no further management of the token is done by Themis. *************** ThemisML Server *************** +.. TODO: Remove once Athena is fully integrated +.. note:: *This section will be removed once feedback suggestions are completely integrated into Artemis.* When notifying or requesting feedback suggestions from ThemisML, the request has to contain the jwt token for Artemis of the requesting user. ThemisML only uses the token to make requests to the Artemis server and does not store the token. diff --git a/docs/system/data-management.rst b/docs/contributor/system-design/data-management.rst similarity index 90% rename from docs/system/data-management.rst rename to docs/contributor/system-design/data-management.rst index 32dcc930..588b8a0f 100644 --- a/docs/system/data-management.rst +++ b/docs/contributor/system-design/data-management.rst @@ -1,15 +1,12 @@ Persistent Data Management -=========================================== - -*************** -Themis iPad App -*************** +-------------------------- The app stores the authentication cookie in the HTTPCookieStorage, which is described in the :ref:`Access Control and Security` Chapter. +*************** UserDefaults ------------- +*************** The app stores the selected Course ID (which are the ones provided by Artemis) in the UserDefaults at **"shownCourseIDKey"** in order to always show the last selected course. @@ -19,6 +16,9 @@ The Artemis server URL is also stored in the UserDefaults at **"serverURL"**. *************** ThemisML Server *************** +.. TODO: Remove once Athena is fully integrated +.. note:: *This section will be removed once feedback suggestions are completely integrated into Artemis.* + ThemisML has a Postgres database separate from the Artemis database to store existing feedbacks for given submissions. The choice of the database follows a related project to ThemisML, `Athene`_. In principle, ThemisML could use the Artemis database directly, but the development team decided to use a separate database for a faster development cycle and more flexibility. The database might be merged in the future. diff --git a/docs/system/global-software-control.rst b/docs/contributor/system-design/global-software-control.rst similarity index 86% rename from docs/system/global-software-control.rst rename to docs/contributor/system-design/global-software-control.rst index 0ccd222e..821b26ad 100644 --- a/docs/system/global-software-control.rst +++ b/docs/contributor/system-design/global-software-control.rst @@ -1,5 +1,7 @@ -Global Software control -=========================================== +Global Software Control +------------------------ +.. TODO: Remove once Athena is fully integrated +.. note:: *This section will be removed once feedback suggestions are completely integrated into Artemis.* .. Global software control describes how the global software control is implemented. In particular, this section should describe how requests are initiated and how subsystems synchronize. This section should list and address synchronization and concurrency issues. This section is optional. It should be included if your system is event based, uses the observer pattern or includes a subsystem using push/pull notifications. For details refer to section 7.4.4 in Prof. Bruegge's book. diff --git a/docs/contributor/system-design/images/deployment_diagram.png b/docs/contributor/system-design/images/deployment_diagram.png new file mode 100644 index 00000000..0de9437e Binary files /dev/null and b/docs/contributor/system-design/images/deployment_diagram.png differ diff --git a/docs/contributor/system-design/images/high_level_component_diagram.png b/docs/contributor/system-design/images/high_level_component_diagram.png new file mode 100644 index 00000000..fce15bbd Binary files /dev/null and b/docs/contributor/system-design/images/high_level_component_diagram.png differ diff --git a/docs/contributor/system-design/images/subsystem_decomposition.png b/docs/contributor/system-design/images/subsystem_decomposition.png new file mode 100644 index 00000000..15dd07d8 Binary files /dev/null and b/docs/contributor/system-design/images/subsystem_decomposition.png differ diff --git a/docs/contributor/system-design/system-design.rst b/docs/contributor/system-design/system-design.rst new file mode 100644 index 00000000..95b15a46 --- /dev/null +++ b/docs/contributor/system-design/system-design.rst @@ -0,0 +1,65 @@ +.. _system_design: + +System Design +============= + +.. contents:: Contents + :local: + :depth: 1 + +.. _high_level_design: + +High-Level Design +---------------- +The following diagram shows a high-level overview of three iOS clients, the Core Module containing shared components, +and the Artemis Server. + +.. figure:: images/high_level_component_diagram.png + :align: center + :alt: High-Level Component Diagram + :width: 600 + + High-Level Component Diagram + +.. _server_architecture: + +Themis Subsystem Decomposition +------------------------------ + +The following UML component diagram shows internal details of Themis and its dependencies on ArtemisCore components. +To ensure that the diagram remains comprehensible and uncluttered, we’ve excluded the view models. + +.. figure:: images/subsystem_decomposition.png + :align: center + :alt: Subsystem Decomposition of Themis + :width: 800 + + Subsystem Decomposition of Themis + +The **Authentication** subsystem helps the user authenticate using the **Login** subsystem. Once a user successfully logs in, +the **Course** subsystem takes over, responsible for displaying courses where the user is as a tutor. Additionally, this +subsystem manages the retrieval and presentation of exercises and exams associated with these courses. When the system +needs to present more detail about a particular exam or an exercise, the **Exercise** and **Exam** subsystems come into play. +The **Exam** subsystem primarily focuses on presenting the exercises within an exam context and leverages the **Exercise** +subsystem when the user selects a particular exercise. When the user initiates an assessment on a submission, the +**Assessment** subsystem. + +.. _deployment: + +Deployment +---------- + +The following UML deployment diagram shows a typical deployment of Themis, Artemis application server and Athena server. +The Artemis server communicates with Athena to fetch feedback suggestions. + +.. figure:: images/deployment_diagram.png + :align: center + :alt: Deployment Diagram + + Deployment Diagram + + +.. include:: data-management.rst +.. include:: access-control.rst +.. include:: global-software-control.rst + diff --git a/docs/images/activity_diagram_1.png b/docs/images/activity_diagram_1.png deleted file mode 100644 index 4a85a8de..00000000 Binary files a/docs/images/activity_diagram_1.png and /dev/null differ diff --git a/docs/images/activity_diagram_2.png b/docs/images/activity_diagram_2.png deleted file mode 100644 index fdf582aa..00000000 Binary files a/docs/images/activity_diagram_2.png and /dev/null differ diff --git a/docs/images/activity_diagram_ml.png b/docs/images/activity_diagram_ml.png deleted file mode 100644 index 13a30217..00000000 Binary files a/docs/images/activity_diagram_ml.png and /dev/null differ diff --git a/docs/images/class_diagram.png b/docs/images/class_diagram.png deleted file mode 100644 index 2f097bc5..00000000 Binary files a/docs/images/class_diagram.png and /dev/null differ diff --git a/docs/images/component_diagram.png b/docs/images/component_diagram.png deleted file mode 100644 index a42f2832..00000000 Binary files a/docs/images/component_diagram.png and /dev/null differ diff --git a/docs/images/deployment_diagram.png b/docs/images/deployment_diagram.png deleted file mode 100644 index a180468f..00000000 Binary files a/docs/images/deployment_diagram.png and /dev/null differ diff --git a/docs/images/design_assessment.png b/docs/images/design_assessment.png deleted file mode 100644 index 23c8fb2e..00000000 Binary files a/docs/images/design_assessment.png and /dev/null differ diff --git a/docs/images/design_course.png b/docs/images/design_course.png deleted file mode 100644 index 9f7d5cda..00000000 Binary files a/docs/images/design_course.png and /dev/null differ diff --git a/docs/images/design_exercise.png b/docs/images/design_exercise.png deleted file mode 100644 index 3f8a608d..00000000 Binary files a/docs/images/design_exercise.png and /dev/null differ diff --git a/docs/images/design_feedback-list.png b/docs/images/design_feedback-list.png deleted file mode 100644 index b5850c10..00000000 Binary files a/docs/images/design_feedback-list.png and /dev/null differ diff --git a/docs/images/design_feedback.png b/docs/images/design_feedback.png deleted file mode 100644 index 83fe79f2..00000000 Binary files a/docs/images/design_feedback.png and /dev/null differ diff --git a/docs/images/design_guidelines.png b/docs/images/design_guidelines.png deleted file mode 100644 index 068bcddb..00000000 Binary files a/docs/images/design_guidelines.png and /dev/null differ diff --git a/docs/images/design_save.png b/docs/images/design_save.png deleted file mode 100644 index bb9cd6ab..00000000 Binary files a/docs/images/design_save.png and /dev/null differ diff --git a/docs/images/design_submit.png b/docs/images/design_submit.png deleted file mode 100644 index c188aa3b..00000000 Binary files a/docs/images/design_submit.png and /dev/null differ diff --git a/docs/images/mockup_assessment.png b/docs/images/mockup_assessment.png deleted file mode 100644 index 681972dc..00000000 Binary files a/docs/images/mockup_assessment.png and /dev/null differ diff --git a/docs/images/mockup_feedback.png b/docs/images/mockup_feedback.png deleted file mode 100644 index 2a3cd8fe..00000000 Binary files a/docs/images/mockup_feedback.png and /dev/null differ diff --git a/docs/images/mockup_next-action.png b/docs/images/mockup_next-action.png deleted file mode 100644 index f1af8e00..00000000 Binary files a/docs/images/mockup_next-action.png and /dev/null differ diff --git a/docs/images/mockup_submit.png b/docs/images/mockup_submit.png deleted file mode 100644 index f52f60f0..00000000 Binary files a/docs/images/mockup_submit.png and /dev/null differ diff --git a/docs/images/use_case_diagram.png b/docs/images/use_case_diagram.png deleted file mode 100644 index 40e03da6..00000000 Binary files a/docs/images/use_case_diagram.png and /dev/null differ diff --git a/docs/index.rst b/docs/index.rst index b07b1fcd..a541cb6a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,57 +1,40 @@ .. _themis: ====================================================== -Themis: Artemis Tutor Grading App for iPad +Themis: Artemis Tutor App for iPad ====================================================== +.. TODO: Add icon +Themis is an innovative iPad app providing a comprehensive and optimized way for tutors to assess student submissions +on the go. As a complementary extension to the `Artemis `_ platform, +an open-source learning management system used at universities, Themis allows tutors to effortlessly +inspect students' submissions and provide feedback. + +Designed as a native iPad application, Themis optimizes viewing and assessing exercises on a mobile +device. Its' intuitive interface and user-friendly assessment editor enable tutors to give general as well as +referenced feedback for programming, text, modeling, and file upload exercises. Leveraging the iPad's unique features +allows a more convenient and streamlined feedback process using Themis. By supporting the Apple Pencil, tutors can +highlight specific segments and provide comments using the Scribble feature. + +Through the connection to the Artemis server, tutors can log in and select the corresponding course as usual to +seamlessly continue the assessment on the go. To enhance the feedback process even further, Themis assists tutors by +providing feedback suggestions. By analyzing submissions and comparing past feedback from previous assessments, feedback +suggestions fitting to current submissions are proposed. The suggestions are displayed for tutors to review and modify +as needed, improving the accuracy and efficiency of the assessment process. .. toctree:: - :caption: Introduction - :includehidden: - :maxdepth: 3 - - introduction/purpose - -.. toctree:: - :caption: Requirements - :includehidden: - :maxdepth: 3 - - requirements/visionary - -.. toctree:: - :caption: Analysis + :caption: Contributor Guide :includehidden: - :maxdepth: 3 - - analysis/ui - analysis/use-case-model - analysis/analysis-object-model - analysis/dynamic-model + :maxdepth: 2 -.. toctree:: - :caption: System Design - :includehidden: - :maxdepth: 3 - - system/overview - system/subsystem-decomposition - system/hw-sw-mapping - system/data-management - system/access-control - system/global-software-control + contributor/system-design/system-design + contributor/guidelines/guidelines + contributor/dev-process/development-process .. toctree:: - :caption: Product Backlog + :caption: Administrator Guide :includehidden: - :maxdepth: 3 - - backlog/backlog + :maxdepth: 2 -.. toctree:: - :caption: Administrator Manual - :includehidden: - :maxdepth: 3 - admin/app/index admin/themisml/index admin/issues \ No newline at end of file diff --git a/docs/introduction/purpose.rst b/docs/introduction/purpose.rst deleted file mode 100644 index 9fb11edc..00000000 --- a/docs/introduction/purpose.rst +++ /dev/null @@ -1,27 +0,0 @@ -Purpose of the System -=========================================== - -**Themis: iPad app for tutors using Artemis** - -Themis is an innovative iPad app providing a comprehensive and optimized way for tutors to assess submitted -programming exercises on the go. As a complementary extension to the `Artemis `_ platform, -an open-source learning management system used at universities, Themis allows tutors to effortlessly -inspect students' code and provide feedback on submissions. - -Designed as a native iPad application, Themis optimizes viewing and assessing programming exercises on a mobile -device. Its' intuitive interface and user-friendly assessment editor enable tutors to give both general as well as -code-specific inline feedback. Leveraging the iPad's unique features allows a more convenient and streamlined feedback -process using Themis. By supporting the Apple Pencil, tutors can highlight specific code segments and provide comments -using the Scribble feature. - -Through the connection to the Artemis server, tutors can log in and select the corresponding course as usual to -seamlessly continue the assessment on the go. To enhance the feedback process even further, Themis assists tutors while -providing more suitable and effective feedback. For this, `Themis-ML `_ is -incorporated, a system for automated feedback suggestions of programming exercises. By analyzing the code and -comparing past feedback from previous assessments, fitting feedback to current submissions is proposed. This -smart feedback is displayed for tutors to review and modify as needed, improving the accuracy and efficiency of the -assessment process. - - - - diff --git a/docs/requirements/visionary.rst b/docs/requirements/visionary.rst deleted file mode 100644 index ba965080..00000000 --- a/docs/requirements/visionary.rst +++ /dev/null @@ -1,29 +0,0 @@ -Visionary Scenarios -=========================================== - -In the following, the requirements of the Themis iPad App are explained by means of visionary scenarios. The presented three scenarios describe the most important functionality that was developed and contain the following actors: - -| Anna: Tutor in the iPraktikum’s intro course -| Tim: Tutor in the lecture-based course Patterns in Software Engineering - -| - -**Scenario 1: Inspect student submissions for programming exercises** - -Anna is asked by a student, why the latest submission does not pass a specific automatic test. Anna opens the app on her iPad and navigates to the latest submission of the student. On the left of the screen a file tree of all the files in the student’s repository is displayed. Anna taps on the first file. The app opens the file and displays the source code in the editor alongside the file tree. The editor also supports syntax highlighting, which helps Anna to understand the code and how it is structured quickly. Anna does not find any issues in the first file, so she taps on the next file in the file tree and the corresponding source code is displayed in the editor view. In this file, Anna notices that the student returns the wrong value inside a function. The student can easily correct the mistake and submit again. - -| - -**Scenario 2: Assess student submissions by giving (inline) feedback** - -Tim is assigned for correcting the programming exercises of the Patterns in Software Engineering exam. He opens the app and navigates to one of the exam’s programming exercises. The app shows details about the specific exercise such as its task description and statistics indicating how many submissions still need to be assessed. As the currently selected exercise still has submissions that are not assessed yet, Tim taps on a button stating Assess next submission. - -As a result, the app opens one of the unassessed student submission in its editor view. Tim looks through the student’s code and identifies that the wrong software pattern was implemented for the task. Therefore, he uses his stylus to input an individual, handwritten feedback for the student, which the application immediately transforms to text. Tim also assigns a score reduction of three points to this general feedback. - -Tim wants to give inline feedback to a specific code segment. He simply selects the lines of codes he wants to give feedback for. The editor then visually indicates the selected code segment and also provides a popup allowing Tim to enter the feedback and corresponding score reduction. Tim has no more feedback to give to the current submission, so he taps on the submit button. - -| - -**Scenario 3: Provide automatic feedback suggestions** - -Anna wants to assess the latest available homework submission. She opens the app, navigates to the first homework exercise. Besides the exercise task description, the app also displays a button to assess the next submission, which Anna taps. The app loads the corresponding submission and displays the file tree. A feedback icon is shown next to some of the filenames. This indicates that automatic feedback suggestions are available for these files. Anna taps on the first file appended with such an icon and the corresponding source code is shown in the editor. Additionally, some of the code segments are highlighted to indicate the existence for automatic feedback suggestions. Anna taps on the first suggestions and the app opens a popup showing the proposed feedback. Anna reads the feedback and concludes that it is also suitable for the current student’s code segment, so she taps a button to use the feedback as well. diff --git a/docs/system/hw-sw-mapping.rst b/docs/system/hw-sw-mapping.rst deleted file mode 100644 index 896eb695..00000000 --- a/docs/system/hw-sw-mapping.rst +++ /dev/null @@ -1,26 +0,0 @@ -Hardware/Software Mapping -=========================================== - -The diagram below shows the hardware and software mapping of the system. -Themis is used by tutors on an iPad. Feedback suggestions are provided by the **Assessment Subsystem** within the app which depends -on the **Submissions Subsystem** of the **Artemis Server** and the **Automatic Feedback Subsystem** of the **Themis-ML Server**. -Communication between nodes are facilitated by REST API. -Please refer to `Artemis documentation`_ and :ref:`Themis-ML` for more details regarding its deployment. - -Artemis' **Submissions Subsystem** depends on an **Exercise Subsystem** within the server, -which provides service for managing programming exercises and their configuration. -This subsystem in turn requires Themis' **Automatic Feedback Subsystem** , -which provides a tutor's feedback for a given submission. - -Themis' **Assessment Subsystem** also requires the **Automatic Feedback Subsystem** of the **Themis-ML** server in order to provide feedback suggestions to the tutor. - - -.. figure:: ../images/deployment_diagram.png - :alt: Deployment diagram of Themis - :align: center - :width: 600 - - *Deployment overview* - - -.. _Artemis documentation: https://docs.artemis.cit.tum.de/dev/system-design/#deployment diff --git a/docs/system/overview.rst b/docs/system/overview.rst deleted file mode 100644 index 92f75a94..00000000 --- a/docs/system/overview.rst +++ /dev/null @@ -1,15 +0,0 @@ -Overview -=========================================== - -.. Include and describe the Workflow here in terms of the main components and technologies used. - -Themis is a native iPad app using SwiftUI, which mainly communicates with Artemis-Servers via REST calls. -It also communicates with a ThemisML server written in Python for the feedback suggestions feature. - -Typically, a tutor will open the Themis iPad App on their iPad and log in to the Artemis server of their choice. They can choose any Artemis server URL, which will be saved for future use. -Once logged in, they can choose a course and an exercise from the respective lists of available courses and exercises. The tutor can then start the exercise and begin grading student submissions. -When opening a submission, the app will initiate a request to ThemisML, which is authenticated with the very same token that's used for the connection to Artemis. ThemisML will then request the submission from the Artemis server (of which the URL is included in the request) and return a list of feedback suggestions. - -After the tutor submitted the assessment, the app will send a request to Artemis with the submission. Also, the ThemisML server will be notified with the ID so that it can update its internal state. - -The ThemisML server can be deployed independently from Artemis. diff --git a/docs/system/subsystem-decomposition.rst b/docs/system/subsystem-decomposition.rst deleted file mode 100644 index db9dee9c..00000000 --- a/docs/system/subsystem-decomposition.rst +++ /dev/null @@ -1,17 +0,0 @@ -Subsystem Decomposition -=========================================== - -This section aims to describe the top-level view of the system in terms of components, subsystems and the dependencies among components, respectively subsystems. - -.. image:: ../images/component_diagram.png - -The system can be divided into four major subsystems. - -The **Exercise Subsystem** is provided by Artemis and contains the **Course** and **Exercise** components. The dependency between an exercise and its corresponding course is modeled as shown. -This subsystem provides the *Task Processing Service* to the **Submission Subsystem** that allows access to an exercise in order to work on it. - -The **Submission Subsystem** is also provided by Artemis and contains the **Student** and **Submission** components with the **Submission** component depending on the **Student**. - -The **Assessment Subsystem** contains the **Feedback** component that depends on the **Guidelines** and the **Tests**. It provides the *Feedback Service* to the **Submission Subsystem** and enables the addition of feedback to a submission. - -The **Automatic Feedback Subsystem** represents the machine learning component of the system. Inside, it contains the **FeedbackModel** and the **FeedbackSuggestions** components. The **FeedbackModel** provides the *Similarity Computation Service* to the **FeedbackSuggestions**. The subsystem in return provides the *Notification Service* to the **Submission Subsystem** and the *Feedback Suggestions Service* to the **Assessment Subsystem**.