diff --git a/Rewritten-docs.md b/Rewritten-docs.md index e5e9a69..5735bc3 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -145,7 +145,7 @@ by instructed privileged users. Assigning an exercise to a group means to choose one of the available exercises and specifying additional properties. An assignment has a deadline (optionally a second deadline), a maximum amount of points, a configuration for calculating the final score, a maximum number of -submissions, and a list of supported runtime environements (e.g., programming +submissions, and a list of supported runtime environments (e.g., programming languages) including specific time and memory limits for each one. Typical use cases for supported user roles are illustrated on following UML @@ -221,7 +221,7 @@ addons (mostly administrative features). specific properties set (deadlines, etc.) - user can see a list of submitted solutions for each assignment with corresponding results -- teachers can specify way of computation grading points which will be awarted +- teachers can specify way of computation grading points which will be awarded to the students depending on the quality of his/her solution for each assignment extra - teachers can view detailed data about their students (users of a their groups) @@ -283,7 +283,7 @@ quickly understand the code and make changes. To find out the current state in the field of automatic grading systems we did a short market survey on the field of automatic grading systems at universities, -programming contests, and possibly other places where similat tools are +programming contests, and possibly other places where similar tools are available. @@ -458,7 +458,7 @@ The application interacts with users. From the project assignment is clear, that the system has to keep personalized data about users and adapt presented content according to this knowledge. User data cannot be publicly visible, so that implies necessity of user authentication. There are several way of -auhtentication user in web applications. HTTP basic authentication has a few +authentication user in web applications. HTTP basic authentication has a few drawbacks like sending plain credentials in every request or no logout option, so it is not recommended to use. Using cookies is possible, but it is susceptible to various types of attacks including stealing and also brings state @@ -478,30 +478,30 @@ least power, basically can just view assignments and submit solutions. Supervisors have more authority, so they can create exercises and assignments, view results of students etc. From the university organization, one possible level could be introduced, _course guarantor_. However, from real experience all -duties related with lecturing of labs are already associtated with supervisors, +duties related with lecturing of labs are already associated with supervisors, so this role seems not so useful. In addition, no one requested more than three level privilege scheme. School labs are lessons for some students lead by one (or sometimes two or -three) supervisors. Students have the same homeworks and supervisors are -evaluating them. This organization has to be carried into the new system. -Counterpart to real labs are virtual groups. This concept was already discussed -in previous chapter including need for hierarchical structure of groups. Right -for attending labs has only a person, who is student of the university and is -recorded in university information system. To allow restriction of group members -in ReCodEx, there two type of groups -- _public_ and _private_. Public groups -are open for every registered users, but to become a member of private group one -of its supervisors have to add that user. This could be done automatically at -beginning of the term with data from information system, but unfortunately there -is no such API yet. However, creating this API is now considered by university -leadership. Another just as good solution for restricting membership of a group -is to allow anyone join the group with supplementary confirmation of -supervisors. It has no additional benefits, so approach with public and private -groups is implemented. +three) supervisors. Students have the same homework and supervisors are +evaluating its solutions. This organization has to be carried into the new +system. Counterpart to real labs are virtual groups. This concept was already +discussed in previous chapter including need for hierarchical structure of +groups. Right for attending labs has only a person, who is student of the +university and is recorded in university information system. To allow +restriction of group members in ReCodEx, there two type of groups -- _public_ +and _private_. Public groups are open for every registered users, but to become +a member of private group one of its supervisors have to add that user. This +could be done automatically at beginning of the term with data from information +system, but unfortunately there is no such API yet. However, creating this API +is now considered by university leadership. Another just as good solution for +restricting membership of a group is to allow anyone join the group with +supplementary confirmation of supervisors. It has no additional benefits, so +approach with public and private groups is implemented. Supervisors using CodEx in their labs usually set minimum amount of points required to get a credit. These points can be get by solving assigned exercises. -To visualy show users if they already have enough points, ReCodEx groups +To visually show users if they already have enough points, ReCodEx groups supports setting this limit. There are two equal ways how to set a limit -- absolute value or relative value to maximum. The latter way seems nicer, so it is implemented. The relative value is set in percents and is called threshold. @@ -1010,7 +1010,7 @@ worker) and how they can be accessed and written into configuration. For this kind of task we have to introduce some kind of marks or signs which will represent particular folders. Marks or signs can have form of some kind of special strings which can be called variables. These variables then can be used -everywhere where filesystems paths are used within configuration file. This will +everywhere where filesystem paths are used within configuration file. This will solve problem with specific worker environment and specific hierarchy of directories. Final form of variables is \${...} where triple dot is textual description. This format was used because of special dollar sign character which @@ -1129,7 +1129,7 @@ worker. It should be like the last salvation in case everything else goes wrong. There are numerous ways how to approach sandboxing on different platforms, describing all possible approaches is out of scope of this document. Instead of that have a look at some of the features which are certainly needed for ReCodEx -and propose some particular sandboxes implementations on linux or Windows. +and propose some particular sandboxes implementations on Linux or Windows. General purpose of sandbox is safely execute software in any form, from scripts to binaries. Various sandboxes differ in how safely are they and what limiting @@ -1169,15 +1169,15 @@ sandbox solution for ReCodEx. With this being said we can safely state that designing and implementing new general sandbox for Windows is out of scope of this project. -New general sandbox for Windows is out of bussiness but what about more +New general sandbox for Windows is out of business but what about more specialized solution used for instance only for C#. CLR as a virtual machine and runtime environment has a pretty good security support for restrictions and -separation which is also transfered to C#. This makes it quite easy to implement -simple sandbox within C# but suprisingly there cannot be found some well known -general purpose implementations. As said in previous paragraph implementing our -own solution is out of scope of project there is simple not enough time. But C# -sandbox is quite good topic for another project for example semestral project -for C# course so it might be written and integrated in future. +separation which is also transferred to C#. This makes it quite easy to +implement simple sandbox within C# but surprisingly there cannot be found some +well known general purpose implementations. As said in previous paragraph +implementing our own solution is out of scope of project there is simple not +enough time. But C# sandbox is quite good topic for another project for example +term project for C# course so it might be written and integrated in future. ### Fileserver @@ -1187,7 +1187,7 @@ for C# course so it might be written and integrated in future. @todo: what can be stored on fileserver -@todo: how can jobs be stored on fileserver, mainly mention that it is nonsence to store inputs and outputs within job archive +@todo: how can jobs be stored on fileserver, mainly mention that it is nonsense to store inputs and outputs within job archive ### Monitor @@ -1267,7 +1267,7 @@ and we were able to develop all the features we needed without learning to use a new technology. Since the number of features was quite high and needed to meet a strict deadline. This does not mean that we would find all the other technologies superior to PHP in all other aspects - PHP 7 is a mature language -with a huge comunity and a wide range of tools, libraries, and frameworks. +with a huge community and a wide range of tools, libraries, and frameworks. We decided to use an ORM framework to manage the database, namely the widely used PHP ORM Doctrine 2. This framework has a robust abstraction layer DBAL so @@ -1283,19 +1283,20 @@ patterns used in this framework (e.g., dependency injection, authentication, routing). There is a good extension for the Nette framework which makes usage of Doctrine 2 very straightforward. -@todo: what database can be used, how it is mapped and used within code - -@todo: authentication, some possibilities and describe used jwt +@todo: authentication, some possibilities and describe used jwt (mentioned in +basic concepts, maybe elaborate more or just remove this item from todo list) @todo: solution of forgotten password, why this in particular @todo: rest api is used for report of backend state and errors, describe why and other possibilities (separate component) -@todo: what files are stored in api, why there are duplicates among api and fileserver +@todo: mail reports - to users, admins -@todo: why are there instances and for which they can be used for, describe licences and its implementation +@todo: what files are stored in api, why there are duplicates among api and fileserver -@todo: groups and hierarchy, describe arbitrary nesting which should be possible within instance and how it is implemented and how it could be implemented +@todo: groups and hierarchy, describe arbitrary nesting which should be possible +within instance and how it is implemented and how it could be implemented +(describe only implementation if it is something what to say) @todo: where is stored which workers can be used by supervisors and which runtimes are available, describe possibilities and why is not implemented automatic solution @@ -1344,7 +1345,7 @@ for the technical description of the components) ### Monitor -@todo: not necessary component which can be ommited, proxy-like service +@todo: not necessary component which can be omitted, proxy-like service ## Backend internal communication