- 04/18/09 23:29:04 (4 years ago)
v6 v7 5 5 == Module design == 6 6 === Separation of GUI & program logic === 7 One of the fundamental goals of Patchwork was to separate the logic of the repository communication from the GUI components. In this connection it is possible to develop the GUI independently from the interface and additionally the Patchwork GUI components could be used to manage other open source code management systems. In the moment the separation can only be used in a limited way (look at "known problems" section). 7 One of the fundamental goals of Patchwork was to separate the repository logic and the user interface. Therefore it should be possible to develop the GUI on top of an interface layer Darcs. Additionally the Patchwork GUI components could be used as a frontend for other source code management systems by changing the interface layer, but this would only be nice to have and is no major goal. 8 We have not reach the separation yet. The Patchwork.GUI.* modules use some Darcs functions directly which should be wrapped in the future. 8 9 9 10 === Patchwork source === 10 In the following you can find the description which modules are included, where they are stored in the Patchwork source and which functions they execute: 11 In the following 11 12 ==== Root ==== 12 ===== Patchwork.hs ===== 13 This is a standalone application with its own main function. Dependant on the parameters of the commando shell (changes, push, pull) a main GUI will be created. If there is no parameter provided then a GUI window will be displayed where you can select from these options. In the current release there exists the following parameters for command shell:[[BR]] 13 ===== patchwork.hs ===== 14 This is a standalone application with the main function of Patchwork. According to the given command line argument (changes, push, pull or help) a main GUI will be created. If no command was specified, a selection-window will pop up. 15 In the current release there exists the following parameters for command shell:[[BR]] 14 16 help: Displays an overview of all provided parameters. This would also be called if the parameter can not be identified.[[BR]] 15 17 changes: Prints an overview of the repository patch history.[[BR]] … … 18 20 19 21 ==== Patchwork.DIL ==== 20 This directory contains the !DarcsInterfaceLayer (DIL). DIL builds the interface to darcs. Parts of the implementation were extracted or refactored from darcs. So the code is used redundant in the darcs code and in the Patchwork code. For the moment there were no other possibilities, because the darcs API is not totally opened and is also not primarily thought to be an API (see "known problems and possible future work"). DIL is divided into the following modules: 22 This directory contains the !DarcsInterfaceLayer (DIL). DIL is the interface to darcs. Parts of the implementation were extracted or refactored from darcs. So the code is very redundant with the Darcs code. We decided to use this way because there exists no real API for Darcs. Instead, most of the functions are exported - but not everything we needed (see "known problems and possible future work"). Furthermore, we broke up the functions which realize the Darcs commands to separate user interface and program logic. DIL could be a starting point to create an API for Darcs. 23 DIL is divided into the following modules: 21 24 ===== Data.hs ===== 22 This module contains the types and access functions. As types there are !PatchInfo and !PatchInfoWithDeps.[[BR]] 25 This module contains the types and some helper functions. There mainly two types at the moment: !PatchInfo and !PatchInfoWithDeps. 26 [[BR]] 23 27 !PatchInfo: Patch data structure for the GUI[[BR]] 24 28 !PatchInfoWithDeps: Patch with lists of dependencies 29 25 30 ===== DarcsAPI.hs ===== 26 This module provides functions to work with the repositories for example getting placed patches. Also it provides functions to convert darcs patches to GUI data structures. 31 This module provides functions to work with the repositories for example getting placed patches. Also it provides functions to convert darcs patches to GUI data structures. 27 32 28 33 ==== Patchwork.GUI ==== 29 Here you will find [http://haskell.org/haskellwiki/Grapefruit Grapefruit] based darcs frontends. Following modules are available: 34 Here you will find [http://haskell.org/haskellwiki/Grapefruit Grapefruit] based ollowing modules are available: 30 35 ===== !PatchView.hs ===== 31 36 Circuit with a !SetView, which shows the patch infos. This is not a discrete command of Patchwork and it will be used by other GUI-commands (changes, push, pull) to show patch infos. 32 37 ===== Changes.hs ===== 33 Shows a list of patches from the local repositories in a !PatchView. This view is accessible under the command line via'darcs changes'. 38 Shows a list of patches from the local repositories in a !PatchView. 'darcs changes'. 34 39 ===== !PushPull.hs ===== 35 Provides the functions 'darcs push' and 'darcs pull' . The circuit is for both commands the same. Dependent on the mode (push or pull) only the input and output is different. There are two !PatchViews included (local and remote repository). In the push mode the patches are in the 'local repository'-!PatchView and in the pull mode they are in the 'remote repository'-!PatchView. Using the arrow buttons („<<<“. „>>>“) to select and deselect patches. With the command buttons ('Push','Pull') the action can be executed. 40 Provides the functions 'darcs push' and 'darcs pull' . The circuit is the same for both commands. Dependent on the mode (push or pull) only the input and output is different. 41 There are two !PatchViews included - one for the local and one for the remote repository. In push mode the patches are in the 'local repository'-!PatchView and in the pull mode they are in the 'remote repository'-!PatchView. Using the arrow buttons („<<<“. „>>>“) to select and deselect patches you can build a set of patches to push or to pull. With the command button ('Push' or 'Pull') the action will be executed. So the GUI replaces the question-answer-procedure on the command line. 36 42 ===== Main.hs ===== 37 This module is the main window from which all commands can be reached. This GUI window is called every time if no command parameter was passed. 43 This module is the main window from which all commands can be reached. 38 44 39 45 == Known problems and possible future work == 40 Currently there exists a bug in push/pull functionality. The selection and takeover from patches works only correct for the first selection, for example in the case when you use the push mode from the local repository to remote repository. This malfunction is a known bug in Grapefruit and his developer works currently with all his passion to solve this problem. Is this problem solved a bug fix will be provided.[[BR]] 41 For developing Patchwork in a useful and fast way the communication between us and the darcs developers must be forced. The goal of the darcs developers should be to develop a better (native) API for eliminating the code redundancy (see Patchwork.DIL).[[BR]] 42 It seems wise for us to integrate Patchwork GUI directly into darcs. Currently the functionality was copied, splatted up and the input and output was processed directly in th GUI. The file !PushPull.hs provides useful information and steps how to integrate Patchwork GUI into darcs.[[BR]] 43 The analysis of the darcs source code was difficult because many signifiers were not chosen meaningful enough and they were not defined well (for example us, us'). Also a rich use of comments in the code would be useful to us in the beginning. In this connection all these reasons are responsible for analyzing the code in a non easy way and new developers could be scared to start with it.[[BR]] 44 For shifting the code we use tabulators, which is known as a standard for formatting code. In contrast the darcs code is formatted with whitespaces which made it not so easy to adapt it. 46 Due to the early development state of Grapefruit, there are still some bugs influencing the functioanlity of Patchwork. 47 48 In push/pull functionality: The selection and takeover from patches works only correct for the first selection, for example in the case when you use the push mode from the local repository to remote repository. This malfunction is a known bug in Grapefruit's set view widget and his developer currently works with all his passion to solve this problem. If the problem is fixed in Grapefruit, Patchwork should work fine. Maybe some changes will be neccessary to because the Grapefruit interface could change. 49 There are also some drawing problems in Grapefruit (or gtk2hs), which should be solved in later versions. 50 [[BR]] 51 52 == For Darcs developers == 53 Patchwork's GUI modules could be directly integrated into Darcs. Therefore you will need to break up the commands into parts of user interaction and parts of pure program logic which do not depend on the way of UI. 54 For an example see the module Patchwork.GUI.PushPull. There is a function called runPuPu with a detailed comment. There you can see how we separated the Darcs logic and the UI. It is also a nice example how you could enhance the readability of your command-functions. 55 In Patchwork.DIL.DarcsAPI you will find the Darcs code we used and how we split it up. 56 [[BR]] 57 The analysis of the darcs source code was very difficult for us because there are far too less comments - even on essential types. 58 Many signifiers do not have meaningful names. 59 Potential Darcs developers who are not forced to deal with it by a study project could be seriously discouraged by your sources.[[BR]] 60 61 62 == Note == 63 We use tabs for indentation!