[prev in list] [next in list] [prev in thread] [next in thread] 

List:       git
Subject:    Re: [GSOC] Contributing to git.
From:       Jakub Narebski <jnareb () gmail ! com>
Date:       2012-03-30 23:37:59
Message-ID: 201203310137.59657.jnareb () gmail ! com
[Download RAW message or body]

On Fri, 30 Mar 2012, jaseem abid wrote:

>>>>     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.
> 
> 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.

>>>>     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.

>> 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.

>>>>     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.

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.
> 
>> 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
--
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
[prev in list] [next in list] [prev in thread] [next in thread]