jquery/contribute.jquery.org

Developer documentation common to jQuery projects

contribute.jquery.org

Developer documentation common to all jQuery projects

Build

To build and deploy your changes for previewing in a jquery-wp-content instance, follow the workflow instructions from our documentation on contributing to jQuery Foundation web sites.

contribute.jquery.org's Issues

Move this site to contribute.jquery.org

We should have done this from the outset, but it makes more sense on .org than .com

This repo name needs to be changed, and the urls have to be changed in jquery/jquery-wp-content sites.php and menu_header.php, and the DNS entries have to be updated.

Import "Won't Fix" page

Importing this here instead of bugs.jquery.com/2

Documentation on setting Git config

We need to document how to set your name and email address in Git. We should link to this from Contributing to Code, Commits and Pull Requests, and even the CLA page.

Community Page

In page/community.md, following the mold of the triage page, put together some information about contributing to the community, including explaining that (obviously) contributing to any of the areas of any project is contributing to the community. The page should go on to explain information about how to get involved with jQuery Events and running local meetups, and link to pages on the site explaining about IRC and support as well.

Document how to file a bug report

Support page

In page/support.md, following the mold of the triage page, put together instructions on the basics of contributing support to other users of jQuery projects, e.g., the forums, IRC, stackoverflow, etc. Should include:

• Links to various resources
• explaining how support is a great way to learn more about projects without needing to run into the problems yourself, learn about intricacies and edge cases and put them in your toolbox
• Advice on giving support
  • talking about being patient, how to coax more information out of people
  • avoiding getting frustrated, it's better to say nothing than editorialise
  • help people solve the problems they need help with, i.e., "Not Telling People The Solution Is To Use a Different CMS"

Document how to be a maintainer

We provide information for contributors, but nothing for maintainers. While we don't add people to jQuery Core, we should generally give out more write access to spread the load. I've never seen anyone abuse that "power", while they usually become more engaged in the project, since they now have more authority and try to make that up in the necessary responsibility.

I've started putting together some guidelines for reviewing PRs, should be valid at least for QUnit and mostly jQuery UI: https://gist.github.com/jzaefferer/a93958b48faa55ff84c5

Do we just give maintainers read access to the CLA document? Or is there some other option?

Should this site be on .com or .org?

Before we get too far down the road of actually setting up the subdomain (cc @gnarf37) , we should have one final discussion on whether the URL for this is contribute.jquery.com or contribute.jquery.org.

I don't have strong feelings either way. @dmethvin and I felt OK about .com but something about .org feels logical as well. Wanted to put this out there for discussion before it's finalised, however, so please give your thoughts on this.

CC @scottgonzalez @jzaefferer @rdworth

Add CSS Style Guide

Add a page that outlines the style guide for CSS across all jQuery projects.

JS style guide: does the camelCase naming convention apply to object properties?

Should either of these be violations:

a.snake_case

{
   snake_case: a
}

Style guides should be moved into a folder

Instead of /js-style-guide/ and /html-style-guide/ we should have a top-level /style-guide/ with /js/ and /html/ inside it. In the future, perhaps we'd add a /css/. This also allows us to have a single style-guide landing page that introduces the concept of sharing all the guides across all foundation projects, and would link to all. It's also consistent with learn.jquery.com/style-guide/

Html and JS style guide links in home page are broken

JS Style Guide: 100 characters for line length too short?

Just looking at the evidence: https://github.com/jquery/jquery/pull/1590/files

It seems like 100 characters might be a nice ideal, but that 120 characters would avoid some of the bending over backwards that we'd have to do.

JS style guide: When to use switch statements, how to format them

Afaik they are only acceptable when a fall-through is needed. Otherwise use if/else.

Reference for formatting:

switch ( event.keyCode ) {
case $.ui.keyCode.ENTER:
case $.ui.keyCode.SPACE:
    z();
    break;
case $.ui.keyCode.ESCAPE:
    y();
    break;
default:
    x();
}

Link to Exceptions has no target

On http://contribute.jquery.org/web-sites/, there's an anchor to "#exceptions":
with some exceptions <a href="#exceptions">*
but there is no corresponding target.

Style Guide page needs fleshing out

As per #14, there is now a top-level style guide page to give background information on our style guides, why following style guide is important, etc. At present, this page is not linked anywhere in the site but does exist.

https://github.com/jquery/contribute.jquery.org/blob/master/pages/style-guide.md

Drop exceptions from JS style guide

Need to look for the others, but the single string argument exceptions needs to go away:

// Nested calls
foo( bar(arg) );

Should be foo( bar( arg ) );

// Single argument string literal, no space
foo("bar");

Should be foo( "bar" ).

// Inner grouping parens, no space
if ( !("foo" in obj) ) {
}

Should be if ( !( "foo" in obj ) ) {

Space omission is allowed when dereferencing an array:
array[0];

Should be array[ 0 ].

This is mostly for syncing with the Core team to see if there are any objections in dropping exceptions.

JS Style Guide: Reference the JSCS options

I would like to have a reference to JSCS options together with JSHint options.

That shoud be a good and quick reference to quick apply the style guide to external projects and to implement in jQuery projects that aren't entirely conformed with it.

Ref qunitjs/qunit#524

JS Style Guide: line length exception for comments with long urls or long regex?

Occasionally, the jQuery codebase goes over 100 characters a line for regexes (and potentially long urls in comments). E.g.:

bool: /^(?:checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|ismap|loop|multiple|open|readonly|required|scoped)$/i,

There are ways to split multiline regexes, but this involves using the constructor and having to double escape backslashes.

Should we make an exception for regex literals and comments? Note I'll be implementing this in JSCS no matter what we decide.

Framed CLA not visible in Firefox

The CLA (http://contribute.jquery.org/CLA/) is not visible in the latest version of Firefox (21.0) on Mac OSX. it is also not visible on Safari 5.1.7 (which is old I admit, but is the latest on Mac OSX 10.6.8). However, it is visible with Safari 6.0.3 on Mac OS X 10.7.5. On both OSs, Chrome will show the form correctly (Version 27.0.1453.116). I am not too worried about Safari 5, but I am about Firefox 21.0.

Link to GitHub's Contributing to OS Guide?

Should we link to https://guides.github.com/overviews/os-contributing/ in our contributing docs?

Document how to setup git (username + email)

https://help.github.com/articles/set-up-git#set-up-git

JS Style Guide: Does top-level indent exception apply to UMD wrappers?

We have this line in the style guide:

If the entire file is wrapped in a closure, the function body is not indented.

Since introducing UMD wrappers in jQuery UI, we use this inconsistently. The wrappers are indented: https://github.com/jquery/jquery-ui/blob/fd7e1e3040ec2c6edb4754135602b5c31678e659/ui/accordion.js#L12

The "factory" isn't: https://github.com/jquery/jquery-ui/blob/fd7e1e3040ec2c6edb4754135602b5c31678e659/ui/accordion.js#L27

We might as well not indent the UMD wrapper.

I noticed this while testing the latest esformatter version with jQuery UI files. esformatter's TopLevelFunctionBlock setting currently doesn't indent any top-level function scope, which used to work well before we introduced the UMD wrappers.

Add heading anchors

e.g. http://contribute.jquery.org/style-guide/js/#type-checks

The wiki supported this, which enabled nice link-ability such as:

http://docs.jquery.com/JQuery_Core_Style_Guidelines#Type_Checks

I'm not sure what format to use, WordPress' slug format would be best imho (to lower case, converting any special characters to dashes).

Maybe it can be done automatically on all content headings from jquery-wp-content, but for now adding here where it would be a regression from the wiki. Especially for coding styling, linking to sections is useful.

JS style guide: Document exception on top-level indentation inside function block

We skip indentation on the first level inside a function block that wraps the entire file.

Port pull request process from UI wiki

http://wiki.jqueryui.com/w/page/40154555/Pull%20Requests

Broken Link: Grid Reference Docs

At the bottom of this page http://contribute.jquery.org/markup-conventions/ there is a link to go to the reference docs for grid.

We'll have a reference eventually, but for now go here to see how to use the grid.

"go here" is a broken link.

JS Style Guide: Rules for long chains

Document how to write long blocks of chained method calls. Include rules for indentation from elements that change the stack.

Small style guide typos

Received via e-mail:

---

Howdy, I was reading the JavaScript Style Guide page on your site and found a couple errors.

Both are in the Multi-line Statements section:

1. In the second example ( ternary operator ), there is a "var" at the beginning which needs removal.
2. In the third example, there is the misspelling of "fistCondition", which should read "firstCondition". It is my assumption that this is not a hidden Chuck Norris joke as it would counter-indicate the style guide recommendations concerning clarity.

That is all for now, Pete

Getting Started with Open Source

In page/open-sourcemd, we should have a page about the basics of getting started with open source, talking about things like

• getting comfortable with the command line, even if you've been reluctant to
• getting used to local development, if you aren't
• advice for interacting positively and proactively in a project, dealing with people who aren't
• the idea that contributing goes beyond just writing code and that projects do value the people who write docs, help users, etc.

More ideas welcome. This page is not really supposed to be specific to jQuery and should be useful to anyone who's been using FOSS and wants some background on how to get involved and how to think about what they're signing up for :)

JS style guide: NaN checks

@Krinkle called me out for a possibly unclear NaN test, and it seems worth including as a type check in the style guide.

Options:

1. name !== name (more compressible; used in Sizzle funescape plus the just-added jQuery core condition)
2. typeof name === "number" && isNaN( name ) (more comprehensible; used in jQuery.style and jQuery.isNumeric, the latter for lack of a variable)

Would anyone object to implementing and documenting option 1?

JS style guide: Formatting ternary expressions

We don't have rules on how to format ternary expressions. Accordingly we have quite a few styles for these:

// from core/css.js
// inline
parts = typeof value === "string" ? value.split(" ") : [ value ];

// from core/css.js
// line break after question mark and colon:
return rnumnonpx.test( computed ) ?
    jQuery( elem ).position()[ prop ] + "px" :
    computed;

// from ui/jquery.ui.progressbar.js
// line break after colon:
return this.indeterminate ? false :
            Math.min( this.options.max, Math.max( this.min, newValue ) );

There's probably more variations.

@dmethvin @scottgonzalez @gibson042 do you have preferences on any of these?

JS Style Guide: Do we need the extra indent for chained method context changes?

In the "Chained Method Calls" section we have this special rule:

If the method changes the context, an extra level of indentation must be used.

This is extremely difficult (practically impossible) to check for automatically (jscs) or format automatically (esformatter).

Could we drop this rule?

JS Style Guide: Clarify object expression in array expression

How should this look like?

var eras = [ {
    "name": "n. Chr.",
    "start": null,
    "offset": 0
} ];

According to the current styleguide, this should be correct. But I suspect the exception for whitespace around object expressions within function arguments also applies to array expressions. Which would look like this instead:

var eras = [{
    "name": "n. Chr.",
    "start": null,
    "offset": 0
}];

CLA: Add note about git config

We should add a note to let contributors know that their git config must match their CLA signature.

A A Cacophony

There is a typo in https://contribute.jquery.org/style-guide/

[…] rather than a a cacophony of competing coders […]

Contributing Code page

In page/code.md, following the mold of the triage page, put together instructions on the basics of contributing code to any jQuery project, e.g., forking repos, making pull requests, writing tests, not removing tests, following the style guide, using grunt, etc, with links to all the project repos.

This should probably link to the Won't Fix page, among other things as well.

Create Prose Style Guide

Most of http://learn.jquery.com/style-guide/ should be moved here as the prose style guide spans everything from READMEs to API documentation to articles and tutorials.

The index page will need to be updated as well, as that links to the various existing guides.

Ensure "Won't Fix" section on positional selectors and Sizzle rewrite is up-to-date

It would seem that a number of the issues discussed in the Won't Fix page are not up-to-date with and make reference a future, but now complete, Sizzle rewrite. This needs to be brought up to date with jQuery 1.8+

cc @timmywil @dmethvin @gibson042

IRC Page?

Since IRC is so crucial to involvement in our projects, should we have a explaining that very fact, and then links to all of our channels, and resources for getting set up, using a bouncer, etc?

Alternatively, this could be maintained as the content of irc.jquery.com.

We'd link to this page in the header.

Import original HTML style guide as markup conventions

The http://jquery.github.com/brand.jquery.org/ style guide is slightly out of date and, and should not be a standalone site anyway. It does not belong in the brand.jquery.org repo after all, as the content is more technical than brand-oriented. Everything else on jquery.github.com has gone to contributed, and this document essentially constitutes our markup conventions.

Document how to contribute translations

Regarding questions like this: "@qunitjs I would like to translate http://qunitjs.com/ pages into Japanese. Can I have a permission to do it?" https://twitter.com/cssradar/status/313666013185077248

Apart from pointing at the license for the content, we want to figure out how to organize translations. One idea that @rdworth or @gnarf37 had in Vienna was to have a repository per locale, with folders for each site repository (the domain names). That way translations can have their own release cycle and contributors.

This may also become work for brand and infrastructure, so this is just a starting point.

Add bug triage boilerplate example replies

Perhaps on the triage page, or on a separate page linked from it, we should codify our example triage answers for various situations - will be useful for us and new prospective triagers.

Adopts mdo's style guide for CSS (and HTML)

This style guide for CSS looks pretty good to me: http://mdo.github.io/code-guide/#css

While that is online and actively maintained, we could just link to it. Its MIT licensed, so we could also integrate it here.

From the HTML section we could take over the sections on "Attribute order" and "Boolean attributes", if we want to adopt those.

Documentation page

In page/documentation.md, following the mold of the triage page, put together instructions on the basics of contributing documentation to any jQuery project, e.g., forking repos, making pull requests, following the style guide, using grunt, etc, with links to all the project repos

Review and Publicize How to Report Bugs

http://contribute.jquery.org/bug-reports/ was ported from MediaWiki and updated to address all projects instead of just core. The content should be reviewed for completeness and links to latest releases and WIP builds for all projects should be included (preferably by linking to pages that will be updated when releases occur).

This page isn't currently discoverable without searching the site.

Port over content from jquery.github.com repo

This site is going to supersede our developer documentation at jquery/jquery.github.com. Move the content here.

Missed URL listed in description area

The description of this repo points to http://contrbute.jquery.org instead of http://contribute.jquery.org

I know, I know, screen shot or it didn't happen:

Contributing to Web Sites page

In page/web.md, following the mold of the triage page, put together instructions on the basics of contributing to jQuery Foundation websites, including:

• high level overview of jquery-wp-content and content repos, why we made it work that way instead of wikis and a million different wordpress installs
• outlining dependencies
• basics of editing workflow and deploy process
• links to all the website repos
• when you'll need to edit web-base-template vs a content repo
• current status of where people should be contributing
• list of exceptions (sites not on jquery-wp-content, whether they ever will be)

Document how to format commit messages

For jQuery UI we have an existing guide for commit messages: http://wiki.jqueryui.com/w/page/25941597/Commit%20Message%20Style%20Guide

We could just put that on this site as-is. We could try to standardise commit messages across our projects, probably something to discuss at the next Dev Leads meeting. Maybe we can gather some input here until that next meeting?

/cc @dmethvin @uGoMobi @Krinkle