Re: The future of gitweb - part 2: JavaScript

2011/4/14 Jakub Narebski [off-list ref]:

quoted

Now that we are talking about future of git, including breaking some
of backwards compatibility bugs / misdesigns for 1.8.0, perhaps it is
the time to discuss long term goals and the future of gitweb.

This is second installment, talking about JavaScript (client-side)
part of gitweb code.

Recently there were sent to git mailing list a new feature which
further extended use of JavaScript in gitweb, namely adjusting common
timezone in which dates are shown:
 http://thread.gmane.org/gmane.comp.version-control.git/169384/focus=169881
 http://thread.gmane.org/gmane.comp.version-control.git/171212

It looks like there would be more proposals on (optional) enhancing
gitweb with JavaScript.

Currently JavaScript is used for the following (optional) features:
* detecting if javascript is enabled (not a feature per se)
* incremental blame (Ajax-y, requires server side knowing above)
* setting local timezone in which dates are shown

Possible other JavaScript-based enhancements include:
* sorting tables like in Wikipedia, avoiding trip to server
* MediaWiki-like history view for selecting commits to compare
 (base does not exist yet, and could be used without JavaScript)


There was one simple issue that for maintenance and readability it is
better to have code split into small modules (into separate files),
while for page performance and interactivity it is better to limit
number of scripts.  This issue can be simply solved by combining
JavaScript files on build.

There was and is more important issue, namely that in our JavaScript
we have to abstract or work around differences in web browsers, and
backport features.  This includes:
* Ajax (generating XmlHttpRequest, handling XHR events)
* emulating getElementsByClassName if native implementation is absent
* workaround differences in setting up event handlers by using
 'elem.onevent = function () { ... }' etc.
* manipulating stylesheets (CSS)

Those issues are already solved in __JavaScript libraries__ and
frameworks, probably better way than in our attempt.  Using JavaScript
framework would also give as higher level constructs, and could
replace what we have and could have in gitweb/static/js/lib:
* popup menu like the one used to select timezone
* date parsing and formatting, string formatting
* handling cookies

Using some JavaScript framework / library could help a lot with
developing and improving JavaScript part of gitweb code.  We would no
longer need to worry so much on how to do it, but could concentrate on
what to do.

Unfortunately the decision to use JavaScript framework brings its own
new problems.

First issue is which JavaScript framework or library to use:
* jQuery (lightweight, most popular, used e.g. by MediaWiki)
* MooTools (lightweight, 2nd most popular, opbject-oriented)
* YUI, The Yahoo! User Interface Library
* other: Prototype, Dojo, ExtJS, SproutCore,...


Second issue is how to use it / how to include it:

* Use some external Content Delivery Network (CDN), like
 Google Libraries API
    http://code.google.com/apis/libraries/devguide.html
 e.g.:

 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.5.2/jquery.min.js"></script>
 <script src="http://code.jquery.com/jquery-1.5.2.min.js"></script>

 or

 <script src="https://ajax.googleapis.com/ajax/libs/mootools/1.3.1/mootools-yui-compressed.js"></script>

 This is nice solution... if we don't need plugin / extension
 which usually are not available in CDN version of library.

 Also this makes gitweb dependent on third-party service, and require
 network connectivity to Internet to have access to JavaScript-based
 features.

* Mark appropriate JavaScript library as dependency in gitweb/INSTALL
 to be downloaded in appropriate place but do not provide sources.
 Perhaps add target in gitweb/Makefile that automatically downloads
 it.

 This would make installing gitweb correctly more complicated.
 JavaScript-based features would not work if somebody instals gitweb
 incorrectly.

 I think we can set up gitweb build so that one can configure at
 build stage whether to use CDN or download library, or use
 pre-downloaded (and perhaps instaled somewhere) version of framework
 (combining JavaScript on build in all but first case).

I'm not sure about pre-downloaded version of libs. Most of the time
it's not a big deal but sometimes it may introduce hard to detect
issues when someone use different version of the lib -
http://ejohn.org/blog/learning-from-twitter/ .But the idea with
options - CDN or download is very good. CDNs can improve the page
download speed by increasing simultaneous connections if files are
downloaded from many hostnames but for companies where instances of
gitweb are on the Intrantet the 2nd option could be better I think (at
least in my case). Additionaly CDNs can save some money when you pay
for data traffic :)

* Provide copy in git sources (in git.git repository), minified or
 development version or both.  This would bloat git repository a bit,
 and we would probably want/have to update library at its releases.

   jQuery      | 24 kB (minified & gzipped), 72 kB (minified),
   MooTools    | 25 kB (minified & gzipped), 86 kB (minified)
   YUI         | 31 kB (library core only)
   Prototype   | 46-278 kB
   Dojo        | 28 kB (minified & gzipped), 65 kB (minified)
   ExtJS       | 84-502 kB

 Some of those, like MooTools[1] and YUI[2], include dependency
 calculator (library builder) where you can get customized version
 with only relevant/required parts included.

 [1]: http://mootools.net/core/  and  http://mootools.net/more/
 [2]: http://developer.yahoo.com/yui/3/configurator/

 Anyway it could be configurable fallback for other methods; this way
 we don't have to keep library up to date.

* Instead of including source code or build (minified) version in git
 repository, we could include JavaScript library as a _submodule_.

 This of course is possible only if library in question procides
 source repository, and if it uses Git for version control (like
 jQuery, MooTools, YUI or Prototype)... or if we can trust our remote
 helper for SCM in question (hmmm... I thought that jQuery uses
 Subversion, but it moved to Git).

 This way you don't need to have it if you don't need it... but on
 the other hand if you need it you have to download (clone) much
 larger development version.  Sidenote: I wonder how well shallow
 clone and narrow checkout works with submodules.

 And of course we would have to somehow integrate build systems,
 i.e. have git call build system of JavaScript library when building
 and installing gitweb.


We can check how other projects solve this issue:

* MediaWiki (jQuery)::

   The jQuery file is in /resources/jquery/jquery.js, loaded
   (and minified) via ResourceLoader since version 1.17

* WordPress (jQuery)::

   jQuery (development version) is in wp-includes/js/jquery/*
   in wordpress RPM

* Movable Type (jQuery)::

   <script type="text/javascript" src="http://www.google.com/jsapi"></script>
   <script type="text/javascript">google.load("jquery", "1.3.2");</script>

* Ruby on Rails (Prototype)

   jQuery (single file) is in gems/rails-*/html/javascripts/prototype.js
   in rails RPM

There is of course question if theirs approach is good for gitweb...


So what are your ideas and comments on the issue of JavaScript code
and JavaScript libraries / frameworks in gitweb?
--
Jakub Narebski
ShadeHawk on #git
Poland
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Pozdrawiam,
Michał Łowicki