[GSOC] Contributing to git.

Hello everyone,

	I was playing around with gitweb project for a couple of days. I
would like to get some more information on the project.
	
	1. Where can I find general instructions on "Contributing to git? "
more specifically, gitweb?
	2. Where can I find coding standards for git? I am looking for the
git version of this document.
		[JQuery core style
guidelines](http://docs.jquery.com/JQuery_Core_Style_Guidelines)
	3. Is JavaScript code unit tested? I cant find much docs regarding
this anywhere.
		I found some general instructions
[here](https://git.wiki.kernel.org/articles/h/o/w/HowToWriteTests_9902.html)
but not for JavaScript.
		I did analyze a few scripts in t/ folder.
		I have shortlisted the following for JavaScript unit testing in
priority order.
		[JSDev by Douglas
Crockford](https://github.com/douglascrockford/JSDev) for its
simplicity and elegance.
		[Jasmine](http://pivotal.github.com/jasmine/) for its power.
		[Sinon.js](http://sinonjs.org/)	- overall goodness.
		
	I would love to hear from you all suggestions on this. A bit of help
for integrating new tests with the existing ones will be of great
help.

Regards,

-- 
Jaseem Abid
+91 8891 72 43 72
S6 CSE student
National Institute of Technology , Calicut.

On Fri, Mar 30, 2012 at 08:19:29AM +0530, jaseem abid wrote:

	1. Where can I find general instructions on "Contributing to git? "
more specifically, gitweb?

Documentation/SubmittingPatches in the git.git repository.

	2. Where can I find coding standards for git? I am looking for the
git version of this document.

Documentation/CodingGuidelines

	3. Is JavaScript code unit tested? I cant find much docs regarding
this anywhere.

Jakub can answer this much better than I can, but I suspect the answer
is "no". We hardly have any javascript at all, and I doubt the gitweb
tests cover the javascript bits.

If there is going to be a javascript-heavy SoC project, I think part of
that should probably be adding some automated testing infrastructure.

-Peff

quoted

Is JavaScript code unit tested? I cant find much docs regarding
this anywhere.

Jakub can answer this much better than I can, but I suspect the answer
is "no". We hardly have any javascript at all, and I doubt the gitweb
tests cover the javascript bits.

If there is going to be a javascript-heavy SoC project, I think part of
that should probably be adding some automated testing infrastructure.

AFAIK now, the gsoc project will be almost JavaScript only and some
Perl. Since this is the main thing I am planning do, I would love to
do it in a good manner.

The current contributors are mainly,
    John 'Warthog9' Hawley <warthog9@**.net>
    Jakub Narebski <jnareb@**.com>
    Petr Baudis <pasky@**.cz>

I would love to get some advice regarding this from them.

-- 
Jaseem Abid
+91 8891 72 43 72
S6 CSE student
National Institute of Technology , Calicut.

On Fri, 30 Mar 2012, Jeff King wrote:

On Fri, Mar 30, 2012 at 08:19:29AM +0530, jaseem abid wrote:

quoted

	1. Where can I find general instructions on "Contributing to git? "
more specifically, gitweb?

Documentation/SubmittingPatches in the git.git repository.

For GSoC we prefer if you had a public git repository with your stuff
(GitHub, repo.or.cz or wherever), and that patches were Cc-ed to mentor.

quoted

	2. Where can I find coding standards for git? I am looking for the
git version of this document.

Documentation/CodingGuidelines

There are no special rules for JavaScript (and neither for that matter
for Perl), but:

  "As for more concrete guidelines, just imitate the existing code
   (this is a good guideline, no matter which project you are
   contributing to). It is always preferable to match the _local_
   convention. New code added to git suite is expected to match
   the overall style of existing code. Modifications to existing
   code is expected to match the style the surrounding code already
   uses (even if it doesn't match the overall style of existing code)."

For JavaScript this includes using subset of JSDoc in comments.

quoted

	3. Is JavaScript code unit tested? I cant find much docs regarding
this anywhere.

No, there are no JavaScript tests at all, neither unit tests
nor procedural (integration) tests.

Jakub can answer this much better than I can, but I suspect the answer
is "no". We hardly have any javascript at all, and I doubt the gitweb
tests cover the javascript bits.

If there is going to be a javascript-heavy SoC project, I think part
of that should probably be adding some automated testing
infrastructure. 

The problem with automated testing of JavaScript is integrating it with
our testsuite, which is run from command line and outputs TAP (Test 
Anything Protocol), so it can e.g. be run by 'prove'.

But even if the JavaScript tests would have to be run in browser (like
most of all of them seems to), having any automated test for gitweb's 
JavaScript code would be a very good idea.

P.S. I wonder how JavaScript-scriptable Veracity DVCS solved that...
-- 
Jakub Narebski
Poland

There are good Opensource tools like
TestSwarm (jQuery) , JSTestDriver(Google) .Both are distributed
javascript testing tools that supports testing on all major browsers.

On Fri, 30 Mar 2012, chaitanyaa nalla wrote:

There are good Opensource tools like
TestSwarm (jQuery), JSTestDriver(Google). Both are distributed
javascript testing tools that supports testing on all major browsers.

We don't need _distributed_ javascript testing tool; we need automated
command-line javascript testing tool which we can integrate into git
testsuite (t/).

* TestSwarm is distributed continuous integration testing tool,
  (not necessary for us), and from what I understand it shows results
  as a web page (in a browser).

  It is written in PHP and uses MySQL.

* jsTestDriver looks like something we could use, as it is run from
  command line, and prints results to standard output.

  It requires however a web browser attached (this is not an obstacle:
  having web browser can be prerequisite for such tests)... and is
  written in Java, and as far as I understand doesn't output TAP.


Documentation/CodingGuidelines says:

 - Avoid introducing a new dependency into git. This means you
   usually should stay away from scripting languages not already
   used in the git core command set [...]

So no PHP, and no Java.

-- 
Jakub Narebski
Poland

I totally agree with your clear explanation Jakub.

chaitanya nalla,
India.

quoted

quoted

    1. Where can I find general instructions on "Contributing to git? "
more specifically, gitweb?

Documentation/SubmittingPatches in the git.git repository.

Generally informative, thank you.

For GSoC we prefer if you had a public git repository with your stuff
(GitHub, repo.or.cz or wherever), and that patches were Cc-ed to mentor.

I just started some experiments with code. I branched 'gsoc'  from
'next' and pushed to github. From the docs I understand that I should
have branched from master. What should I be doing now?
[github clone](https://github.com/jaseemabid/git/tree/gsoc)

quoted

quoted

    2. Where can I find coding standards for git? I am looking for the
git version of this document.

Documentation/CodingGuidelines

There are no special rules for JavaScript (and neither for that matter
for Perl), but:

Parts of my mail are not quoted so I'm mentioning some points again.

Since we don't have a strict coding guidelines for JavaScript till
now, and since we are thinking of an almost rewrite, I would suggest
that we can follow guidelines from the Jquery project.
[http://docs.jquery.com/JQuery_Core_Style_Guidelines]. Since this is
the library we are going to use mostly, I think this will be a good
choice, considering we might write few plugins ourselves for the
project.

[Tips from Douglas
Crockford](http://javascript.crockford.com/code.html ) are very
important in the context of JavaScript. Following this will make it
pass [JSLint](http://www.jslint.com/) which is a good measure for
JavaScript code quality. Will try to make sure that every piece of
JavaScript I write pass JSLint (which is not very easy). I think it is
like the POSIX example from Documentation/CodingGuidelines for C :P

I have tried to follow these till date and wont be hard to continue
doing it for gitweb.

For JavaScript this includes using subset of JSDoc in comments.

[JSDoc]((http://code.google.com/p/jsdoc-toolkit/)) tool kit seems like
a very good choice.

quoted

quoted

    3. Is JavaScript code unit tested? I cant find much docs regarding
this anywhere.

The problem with automated testing of JavaScript is integrating it with
our testsuite, which is run from command line and outputs TAP (Test
Anything Protocol), so it can e.g. be run by 'prove'.

This is what I proposed originally,

		I have shortlisted the following for JavaScript unit testing in
priority order.
		[JSDev by Douglas
Crockford](https://github.com/douglascrockford/JSDev) for its
simplicity and elegance.
		[Jasmine](http://pivotal.github.com/jasmine/) for its power.
		[Sinon.js](http://sinonjs.org/)	- overall goodness.

After reading through the mail and the TAP requirement, I would love
to recommend JSDev and [node.js](http://nodejs.org/) for this task. I
think it can be integrated with TAP well afaik. I need to learn more
about TA. I wont be able to confirm something without knowing much
about it now. I know that we should not be adding more requirements to
git project, but node.js seems trivial for testing JavaScript in a
terminal. Since not many will be developing JavaScript for gitweb, I
dont think its a bad idea.

But even if the JavaScript tests would have to be run in browser

Not necessarily.


-- 
Jaseem Abid
+91 8891 72 43 72
S6 CSE student
National Institute of Technology , Calicut.

On Fri, Mar 30, 2012 at 4:48 PM, chaitanyaa nalla [off-list ref] wrote:

There are good Opensource tools like
TestSwarm (jQuery)

TestSwarm is still in its alpha stage.

JSTestDriver(Google).

Too much for this project. Too many unwanted features.

Both are distributed

does it have to be?

javascript testing tools that supports testing on all major browsers.

Node.js will let us test in a console. Else we can fallback to a browser option.

-- 
Jaseem Abid
+91 8891 72 43 72
S6 CSE student
National Institute of Technology , Calicut.

On 30/03/12 12:05, Jakub Narebski wrote:

But even if the JavaScript tests would have to be run in browser (like
most of all of them seems to), having any automated test for gitweb's 
JavaScript code would be a very good idea.

P.S. I wonder how JavaScript-scriptable Veracity DVCS solved that...

JS test suites generally run in the browser because knowing that your
tests pass in some sane command-line compiler tells you nothing about
how it will be mangled by IE (or in rare cases, other browsers).

IMHO, the best thing to do with JS unit tests would be to make them
easily available from gitweb.  Then when someone reports a bug, you just
ask them to run the tests in their browser - the pattern of errors will
quickly show you that e.g. their AdBlock filters are getting a bit
overexcited about all these `git add`s it can remove (that sort of thing
was a frequently-reported problem at my last job).

Obviously it's good to run tests automatically too - you might want to
consider writing tests with QUnit[1] and automating them with
Selenium[2].  The former is designed to be appealing to human eyes and
trivially testable with the latter (although I'd expect other suites to
include the necessary <div>s with the necessary id's too).  I haven't
used the Perl interface myself, but I'm sure you could make some TAP
output with WWW::Selenium pretty easily.

	- Andrew

1. http://docs.jquery.com/QUnit
2. http://seleniumhq.org/

On Fri, 30 Mar 2012, jaseem abid wrote:

quoted

quoted

quoted

    1. Where can I find general instructions on "Contributing to git? "
more specifically, gitweb?

Documentation/SubmittingPatches in the git.git repository.

[...]

quoted

For GSoC we prefer if you had a public git repository with your stuff
(GitHub, repo.or.cz or wherever), and that patches were Cc-ed to mentor.

I just started some experiments with code. I branched 'gsoc'  from
'next' and pushed to github. From the docs I understand that I should
have branched from master. What should I be doing now?
[github clone](https://github.com/jaseemabid/git/tree/gsoc)

 
As GSoC project wouldn't start until May 21, you can either re-create
'gsoc' branch or rebase it on top of 'master', then force push to GitHub.
 
Note however that it is not given that "Use JavaScript library / framework
in gitweb" would be one of accepted topics in general, and that your
application will be accepted in particular.

quoted

quoted

quoted

    2. Where can I find coding standards for git? I am looking for the
git version of this document.

Documentation/CodingGuidelines

There are no special rules for JavaScript (and neither for that matter
for Perl), but:

Parts of my mail are not quoted so I'm mentioning some points again.

Since we don't have a strict coding guidelines for JavaScript till
now, and since we are thinking of an almost rewrite, I would suggest
that we can follow guidelines from the Jquery project.
[http://docs.jquery.com/JQuery_Core_Style_Guidelines]. Since this is
the library we are going to use mostly, I think this will be a good
choice, considering we might write few plugins ourselves for the
project.

Iam not sure if we would be writing jQuery plugins at all, as opposed
to simply using jQuery.  When writing jQuery plugins we should follow
jQuery Style Guidelines you linked, but for main gitweb.js code...
...I am not sure if following Documentation/CodingGuidelines for C
also in JavaScript wouldn't be a better idea (style consistency),
especially that such style is used already -- no code churn changing
style.

In particular:

* "Be sure to use liberal spacing in your code."  

  I'd rather use liberal but not too liberal spacing:

   if (blah === "foo") {
     foo("bar", "baz", {zoo: 1});
   }

* "if/else/for/while/try always have braces and always go on
  multiple lines"
 
  We don't use braces (blocks) for single-line "if" statements, as
  stated in Documentation/CodingGuidelines: "We avoid using braces
  unnecessarily."  In this case I think that jQuery style might be
  better for JavaScript (less fragile).

* "Always include extra spaces around the arguments."

  I'd rather not.

* "All RegExp operations should be done using .test() and .exec().
  "string".match() is no longer used."

  Perhaps in new code.  I'd rather avoid rewriting existing code
  unnecessarily.  I wonder what is reasoning behind this rule.

[Tips from Douglas
Crockford](http://javascript.crockford.com/code.html ) are very
important in the context of JavaScript.

Please remember that those are best practices, and a some of them
are rather matter of taste, for example using spaces to indent,
and not tabs (tabs to indent, spaces to align... or assume 8 spaces
tabs).

Following this will make it 
pass [JSLint](http://www.jslint.com/) which is a good measure for
JavaScript code quality. Will try to make sure that every piece of
JavaScript I write pass JSLint (which is not very easy). I think it is
like the POSIX example from Documentation/CodingGuidelines for C :P

I have tried to follow these till date and won't be hard to continue
doing it for gitweb.

Well, maybe relaxed JSLint; some of checks are "best practice" checks.
I wouldn't expect C code part of git pass lint / splint, nor Perl
parts Perl::Critic, at least not with most strict checking mode.

quoted

For JavaScript this includes using subset of JSDoc in comments.

[JSDoc]((http://code.google.com/p/jsdoc-toolkit/)) tool kit seems like
a very good choice.

At least there seems to be some common format for structured comments,
as opposed to C (Doxygen, DOC++, ROBODoc,...).

Not that we use jsdoc-toolkit to actually generate automatic API
description; such documentation is is not that helpful anyway.

quoted

quoted

quoted

    3. Is JavaScript code unit tested? I cant find much docs regarding
this anywhere.

quoted

The problem with automated testing of JavaScript is integrating it with
our testsuite, which is run from command line and outputs TAP (Test
Anything Protocol), so it can e.g. be run by 'prove'.

This is what I proposed originally,

		I have shortlisted the following for JavaScript unit testing in
priority order.
		[JSDev by Douglas
Crockford](https://github.com/douglascrockford/JSDev) for its
simplicity and elegance.

This is not unit testing framework.  It is not even testing framework.
It is a bloody source filter (think #ifndef NDEBUG ... #endif on acid).

Please correct me if I am wrong.

		[Jasmine](http://pivotal.github.com/jasmine/) for its power.

This is behavior-driven development framework for testing JavaScript code,
though it looks to be geared towards BDD development method.

Standalone it doesn't provide running from command line, though Node.js
or equivalent (like jsTestDriver) might help there.  It is to be run in
web browser.

		[Sinon.js](http://sinonjs.org/)	- overall goodness.

Hmmm... from description it looks like it is something (stubs and mocks)
that you use in addition to unit testing framework like QUnit, not
a testing framework by itself.

After reading through the mail and the TAP requirement, I would love
to recommend JSDev and [node.js](http://nodejs.org/) for this task. I
think it can be integrated with TAP well afaik. I need to learn more
about TAP. I wont be able to confirm something without knowing much
about it now. I know that we should not be adding more requirements to
git project, but node.js seems trivial for testing JavaScript in a
terminal. Since not many will be developing JavaScript for gitweb, I
dont think its a bad idea.

quoted

But even if the JavaScript tests would have to be run in browser

Not necessarily.

Test.Simple and Test.More (http://search.cpan.org/dist/JS-Test-Simple/)
both output TAP (they are port of Perl's Test::Simple and Test::More);
part of JS::Test::Simple.

Node.js requires V8 JavaScript engine from Google; if we have that, we
can as well use e.g. JavaScript::V8x::TestMoreish[2] from CPAN.

Other solutions include using Test::JavaScript (uses SpiderMonkey
JavaScript engine), or Selenium.

[2] http://search.cpan.org/perldoc?JavaScript::V8x::TestMoreish
-- 
Jakub Narebski
Poland

On Sat, Mar 31, 2012 at 7:37 AM, Jakub Narebski [off-list ref] wrote:

Test.Simple and Test.More (http://search.cpan.org/dist/JS-Test-Simple/)
both output TAP (they are port of Perl's Test::Simple and Test::More);
part of JS::Test::Simple.

Node.js requires V8 JavaScript engine from Google; if we have that, we
can as well use e.g. JavaScript::V8x::TestMoreish[2] from CPAN.

Other solutions include using Test::JavaScript (uses SpiderMonkey
JavaScript engine), or Selenium.

[2] http://search.cpan.org/perldoc?JavaScript::V8x::TestMoreish

Just to add to the discussion, consider these too (descriptions copied
verbatim off their tins):

1. phantomjs[1] - headless WebKit with JavaScript API
2. casperjs[2] - navigation scripting & testing utility for PhantomJS

[1] http://www.phantomjs.org/
[2] http://casperjs.org/

nazri

On Mon, Apr 2, 2012 at 1:02 PM, Nazri Ramliy [off-list ref] wrote:

Just to add to the discussion, consider these too (descriptions copied
verbatim off their tins):

1. phantomjs[1] - headless WebKit with JavaScript API
2. casperjs[2] - navigation scripting & testing utility for PhantomJS

[1] http://www.phantomjs.org/
[2] http://casperjs.org/

It feels like too much for this project. Do we need all the features
from these projects? As far as I can understand, you need phantom.js
to be installed in your local development machine, which is a new
dependency.  I have an instruction from the community not to add new
dependencies.

-- 
Jaseem Abid
+91 8891 72 43 72
S6 CSE student
National Institute of Technology , Calicut.

On Tue, Apr 3, 2012 at 12:26 AM, jaseem abid [off-list ref] wrote:

It feels like too much for this project. Do we need all the features
from these projects? As far as I can understand, you need phantom.js
to be installed in your local development machine, which is a new
dependency.  I have an instruction from the community not to add new
dependencies.

Ah that is true. I forgot about the overhead of getting phantomjs installed.

nazri

On Tue, Apr 3, 2012, Nazri Ramliy wrote:

On Tue, Apr 3, 2012 at 12:26 AM, jaseem abid [off-list ref] wrote:

quoted

It feels like too much for this project. Do we need all the features
from these projects? As far as I can understand, you need phantom.js
to be installed in your local development machine, which is a new
dependency.  I have an instruction from the community not to add new
dependencies.

Ah that is true. I forgot about the overhead of getting phantomjs installed.

Well, we would need to have some JavaScript engine installed for
running tests from commandline, be it Google Chrome's V8 (e.g. node.js),
Mozilla's SpiderMonkey, or WebKit (e.g. phantomjs).

Though I think that having a page with JavaScript tests, to be opened
and checked in browser would be enough for a start.
-- 
Jakub Narebski
Poland