This is the developer wiki of Patchwork
Separation of GUI & program logic
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. We have not reach the separation yet. The Patchwork.GUI.* modules use some Darcs functions directly which should be wrapped in the future.
In 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.
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.
In the current release there exists the following parameters for command shell:
help: Displays an overview of all provided parameters. This would also be called if the parameter can not be identified.
changes: Prints an overview of the repository patch history.
pull: Copies patches from another repository to a repository in which you are.
push: Copies patches from a repository in which you are to another repository.
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. DIL is divided into the following modules:
This module contains the types and some helper functions. There mainly two types at the moment: PatchInfo and PatchInfoWithDeps.
PatchInfo: Patch data structure for the GUI
PatchInfoWithDeps: Patch with lists of dependencies They correspond to types used by Darcs but they do not use these ugly ByteStrings.
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. Here you will find many lines of Darcs code. See the comments there for details.
Here you will find Grapefruit based frontends for the Darcs commands. The following modules are available:
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.
Shows a list of patches from the local repositories in a PatchView. It is the GUI version of 'darcs changes'.
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. 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.
This module is the main window from which all commands can be reached.
Known problems and possible future work
Due to the early development state of Grapefruit, there are still some bugs influencing the functioanlity of Patchwork.
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.
There are also some drawing problems in Grapefruit (or gtk2hs), which should be solved in later versions.
For Darcs developers
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.
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.
In Patchwork.DIL.DarcsAPI you will find the Darcs code we used and how we split it up.
The analysis of the darcs source code was very difficult for us because there are far too less comments - even on essential types. Many signifiers do not have meaningful names. Potential Darcs developers who are not forced to deal with it by a study project could be seriously discouraged by your sources.
We use tabs for indentation!