Changes between Version 6 and Version 7 of WikiStart

Show
Ignore:
Timestamp:
04/18/09 23:29:04 (6 years ago)
Author:
mno (IP: 217.93.105.45)
Comment:

completly refactored

Legend:

Unmodified
Added
Removed
Modified
  • WikiStart

    v6 v7  
    55== Module design == 
    66=== 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). 
     7One 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. 
     8We have not reach the separation yet. The Patchwork.GUI.* modules use some Darcs functions directly which should be wrapped in the future. 
    89 
    910=== 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: 
     11In the following section you can find descriptions for the different modules of the source code. The source files itself are in a well-commented state, so you should also take a look on them. 
    1112==== 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 ===== 
     14This 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.  
     15In the current release there exists the following parameters for command shell:[[BR]] 
    1416help: Displays an overview of all provided parameters. This would also be called if the parameter can not be identified.[[BR]] 
    1517changes: Prints an overview of the repository patch history.[[BR]] 
     
    1820 
    1921==== 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: 
     22This 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. 
     23DIL is divided into the following modules: 
    2124===== Data.hs ===== 
    22 This module contains the types and access functions. As types there are !PatchInfo and !PatchInfoWithDeps.[[BR]] 
     25This module contains the types and some helper functions. There mainly two types at the moment: !PatchInfo and !PatchInfoWithDeps. 
     26[[BR]] 
    2327!PatchInfo: Patch data structure for the GUI[[BR]] 
    2428!PatchInfoWithDeps: Patch with lists of dependencies 
     29They correspond to types used by Darcs but they do not use these ugly ByteStrings. 
    2530===== 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. 
     31This 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. Here you will find many lines of Darcs code. See the comments there for details. 
    2732 
    2833==== Patchwork.GUI ==== 
    29 Here you will find [http://haskell.org/haskellwiki/Grapefruit Grapefruit] based darcs frontends. Following modules are available: 
     34Here you will find [http://haskell.org/haskellwiki/Grapefruit Grapefruit] based frontends for the Darcs commands. The following modules are available: 
    3035===== !PatchView.hs ===== 
    3136Circuit 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. 
    3237===== 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'. 
     38Shows a list of patches from the local repositories in a !PatchView. It is the GUI version of 'darcs changes'. 
    3439===== !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. 
     40Provides 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.  
     41There 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. 
    3642===== 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. 
     43This module is the main window from which all commands can be reached. 
    3844 
    3945== 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. 
     46Due to the early development state of Grapefruit, there are still some bugs influencing the functioanlity of Patchwork. 
     47 
     48In 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. 
     49There are also some drawing problems in Grapefruit (or gtk2hs), which should be solved in later versions. 
     50[[BR]] 
     51 
     52== For Darcs developers == 
     53Patchwork'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. 
     54For 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. 
     55In Patchwork.DIL.DarcsAPI you will find the Darcs code we used and how we split it up. 
     56[[BR]] 
     57The analysis of the darcs source code was very difficult for us because there are far too less comments - even on essential types.  
     58Many signifiers do not have meaningful names. 
     59Potential 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 == 
     63We use tabs for indentation!