[GSoC] draft for my application about api changes/enhancements

[Ronny Pfannschmidt]

Hi,

i pretty much collected various nagging points of different users of the
api.

Some parts are vauge (most notably the changes for commands/error
reporting) as i need to work with the api in order to figure a good way
to do it.

Other parts are research questions that require further investigation in
order to make the api as save and unambigious as possible.

Please comment.

Regards Ronny Pfannschmidt


-------------- next part --------------
1. What project do you want to tackle?

I want to enhance api/gui support of mercurial in various ways.
This includes changes to the ui, the commands modules, error handling as well as general external apis.


2. What design choices will have to be made?

 * divide cli specific parts from the commands/cmdutil modules, 
   turn the rest into a api

 * explore how ui can be improved for reporting to
   user interfaces or notification areas in different threads and processes
 * explore approaches to integrate reporting the current operation/progress into the ui

   * cli version will be opt-in for backward compatibility (alternatively auto-enable on terminals

 * explore the use of exceptions/return values in places 
   where direct error reporting is used to enhance the error handling for library users

 * investigate how hooks affect guis, and what degree of control might be necessary
 * implement a dbus api for accessing mercurial as extension

  * wire-protocol unification (see dcj)

    * extensibility?

  * localrepo.status isn't very helpfull, iterating the workingctx is necessary to figure renames

    * take an example in bzrs WorkingTree.iter_changes ?

  * bundlerepo is ugly, refactor? how?

    * there seems to be MI missuse (gut feeling from the first looks)

* how does extensions.wrapcommand affect the api expectations

* how to extend repo more clean than patching self.class
  * collect mixins ?
    * select mixins based on capabilities/local capabilities

  * should there be a difference between local capabilities (repo formats, workdir extensions) and 
    remote capabilities (wireproto, bundle formats, nested repos for patch queues/subrepos)

* plausibility-checks for commits
  * currently its relatively simple to generate a history that contains files which are named like a basename of other files
    * should the check be explicit or implicit

* better commit building api for in-memory commits
  * generate merges + resolve conflicts without workdir (ie in bare repos, possible uses for vcs backed cms/wiki)
  * builtin memory patch application (as done by bitbucket/thg)
    * patch interface http://bitbucket.org/durin42/hgsubversion/src/tip/fetch_command.py#cl-179
        .. seems that iterhunks is not that wanted, mempatchproxy is

  * imperative commit building on top of the callback based memctx

(Detail how you plan to implement the project. Explain data structures used or changed, compatibility issues, and trade-offs.)

3. What difficulties do you foresee? How do you plan to manage them?

* changes in the internal error reporting 
  are not supposed to change the output of the cli in any case
  * this is supposed to be handled by the integration tests
* the changes will deprecate the ways cutehg/thg/anyvc currently go,
  there is need for collaboration on how stuff will work 
  and how to manage the transition
* changes in error reporting might render the cli/generic split unnecessary
* reporting might need some kind of thread awareness
  at least for async use in gui toolkits via background threads
  however this could be defered to ui subclasses targeted at the specific ui toolkits/applications


(Where do you see potential problems? If you don't know, ask around on mailing lists or IRC.)

4. What intermediate milestones can be defined?

..  this needs reorganisation, sync with the "design choices" and deadlines

* ui progress reporting
* cli/generic split of

  * ui
  * cmmand
  * cmdutil
  * hooks?

* exception introduction
* dbus api
* in memory api's
  * imperative commit
  * merge-resolve
  * patch application


(We need a few of these, so we can check up on your progress. You probably want at least three of these. Start off with some documentation, design options/trade-offs and include tests somewhere.)

5. Who are you?

My name is Ronny Pfannschmidt, and i'm a cs student in Germany.
I'm a core developer of the pida ide and the main author of the anyvc vcs abstraction library.
My prior experience with mercurial is using it from cli as well as the api (mainly in anyvc),
I contributed a minor patch to fix a bug in the export command.