=================
= Configuration =
=================

=========
= Terms =
=========

A `Default` Package:

    This isn't neccessarily just the Packages/Default package
    literally named "Default".

    Through-out I'll put `Default` in backquotes when I mention any
    Packages that are defaults, ie those that come stock with Sublime.

    This includes the Python / HTML / JavaScript packages etc

`asset`:

    A sublime-snippet / sublime-keymap etc inside a Package.

============
= Problems =
============

Exhibit a) A harmless try/except/finally python snippet

<snippet>
    <content><![CDATA[try:
    ${1:pass}
except ${2:Exception}, ${3:e}:
    ${4:raise $3}
finally:
    ${5:pass}]]></content>
    <tabTrigger>try</tabTrigger>
    <scope>source.python</scope>
    <description>Try/Except/Finally</description>
</snippet>

Scenario 1
----------

I'm a typical new user. I'm not using the AutomaticBackups plugin and
I'm definitely not using version control.

*)  I'd like to modify the snippet from exhibit A to change the default
    value of tabstop 1 to $SELECTION. I do so.

*)  It's convenient to just save the snippet in place over writing
    the package version so I do so.

*)  Months and a few betas pass. All is fine in the land.

*)  A new beta comes out and the official `Default` Python Package version of
    the asset gets updated (maybe using new inline Python in the snippets)

*)  On update my modification gets hosed (silently) along with about 12
    other various assets.

*)  I wasn't notified of the updates and they were overwritten silently
    so I only find out the extent of the problem as I go to use my
    snippets / assets.

Scenario 2
----------

I have been using Sublime for a while and have been bitten by the
`silent updates`. I generally use version control on updates (when I
remember to!).

*)  I'd like to modify the snippet from exhibit A to change the default value of
    tabstop 1 to $SELECTION. I do so.

*)  Where do I save? Like a good citizen, I save it in the User
    folder, trying to avoid any possibility whatsoever of overwrites on
    package updates.

*)  Having saved the snippet in my User folder I go to use the
    snippet. There are about 5 snippets with a <tabTrigger> of "try" so
    I now have a duplicate in the `quick panel` for each try/except/* snippet
    I modify.

    The only way I can remove it is modifying the original file ( by deleting
    it or commenting out the <tabTrigger> )

Steps needed for this process:

    *  P[r]eferences - Browse Packages

    *  Find the snippet

    *  Copy it manually into the python folder

    *  Edit it

    *  Delete/comment the original

        * Repeat process after every update to the asset

Scenario 3
----------

I want to tweak a binding declared in one of the `Default` packages
sublime- keymap file. We'll say HTML.sublime-keymap for example but
really the discerning point is that it's a `Default` sublime-keymap
where it's possible it will get over-written silently.

I've been hosed before so I'd like to place my binding in the `User`
sublime-keymap in case I forget to commit/backup before update.

Steps needed for this process:

  *  Per File Type->HTML

  *      Find the binding in question

  *      Copy the binding

  *  Per File Type->User

  *      Paste in the binding

==========================
= Essence Of The Problem =
==========================

*    Users are encourage to modify `Default` package assets such as
     the Python/Default.sublime-keymap and not really warned that it's possible
     their changes will be over written silently

*    It's simply a pain navigating back and forth copy/pasting & saving
     copies to the User folder.

*    No automatic merge of user modified assets (by unique key of fileName or UUID)

====================
= Desired Outcomes =
====================

*  Maintain `hand editability` and aesthetics

    *   no ugly and hard to work with uuid

    *   no mousing about with clicky menu types

*  No losing of modified package `assets`

*  Notification of when modified package `assets` are updated
   ( ie change from `pristine` (earlier) version to
     `latest` version ). If you have `forked off` from the mainline
   you should be notified of any updates to the mainline which
   you may / may not want to incorporate.

=============
= Solutions =
=============

1)  Leave configuration `as is`, editing `Default` package assets in
    place and use `update hooks` for external merge/diff tools to
    manage changes.

2)  Leave config essentially as is but develop `asset cloning`
    commands to clone assets from `Default` packages.

3)  Combinations of the above two

4)  Include UUIDs in assets and create a Package asset manager using
    Virtual Views and QuickPanel navigation.

Update Hooks
============

Hook points for integrating version control. This could be done simply
with subprocess calls to svn/ hg/ vcs of choice. Possibly even custom
sublime-keymap diff/merge tools could be developed using lxml etc.

def preUpdate(window): pass
    """ hooks for add/commit etc """

def postUpdate(window): pass
    """ hooks for things like 'hg status -m;hg status -a` or even
    calls to merge tools etc """

If these `singular` hooks aren't over-ridden then the builtin default
hook would present a basic report of changes, also setting a flag for
the upgrade script to make backups to overwrites of 'user modified'
assets. This is the very least that needs to be done. Having silent
overwrites is unacceptable.

Sublime's configurations paradigm, having no real configuration menus,
is definitely oriented towards `power` users. I don't think it's
stretch having them do assisted merges of configuration on update.  I
think this would be relatively simple to implement and the
participation required would naturally scale according to a users
configuration needs.

A new user would hardly modify anything so wouldn't get bothered (or
confused ) by any update reports. Intermediates would benefit by
learning a bit more about what's going on and long time users would
appreciate the `updates`.

User Asset Cloning
==================

The `best practice` is to keep *all* your key-bindings in the
Packages/User/XXXXX.sublime-keymap file.   ( typically Default )

If this is the case, then there needs to be some type of support
present for editing `existing` keybindings. Rather than opening up the
Python/*keymap and copy/pasting a binding into your User/*keymap a
`cloneBinding` command to do it automatically ( commenting out the
`master` binding ) and take you to the edit point would be nice.

Otherwise, this is a `paint point` where a lot of potential purchasers
of the software walk away. You could have a quick-panel to list all
the bindings for editing (cloning) as well.

Likewise for any snippets or other assets wanting to be edited.

Cloning & VCS Hooks
===================

Commenting out the original (with a slight marking in the comment
`CLONED` ) would serve two purposes.

*   For later `update diffs` to notify user of upstream package updates
    they may want to look at / merge in

*   Don't pollute the bindings namespace with `disabled` keys

On update if an `asset` hasn't changed what so ever, comparing `pristine`
version to the `latest` version then the commented out would not be
updated.

If there has been an update then it will trigger merge notification.

QuickPanel hopping to Virtual Views of `assets`
===============================================

The use of virtual Views to present configuration `dialogs`, navigable
via the QuickPanel and hiding UUID and other versioning metadata.

These snippet `forms` need not even be in XML.

==============
= conclusion =
==============

At the very least the `silent updates` must stop.

Personally I prefer update hooks for their simplicity or UUID +
Virtual Views for real power. Cloning assets into the User folder as a
means of dealing with version by itself seems like a lot of complexity
for very little gain. Using version control renders it practically
pointless.

UUIDs ensure any tidyup to file names for example are manageable.

bzr is the only version control system I can think of that has first
class support for changing filenames and maintaining verson history.
However it has a very checkered history with changes to the core repo
format occuring extremely often