CINXE.COM

<!DOCTYPE html><html lang="en" prefix="og: http://ogp.me/ns#" itemscope itemtype="http://schema.org/WebPage"><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><title>Contributing - Grunt: The JavaScript Task Runner</title><link rel="stylesheet" href="/css/main.css"><link rel="apple-touch-icon" href="/img/favicons/apple-touch-icon.png" sizes="180x180"><link rel="icon" type="image/png" href="/img/favicons/favicon-32x32.png" sizes="32x32"><link rel="icon" type="image/png" href="/img/favicons/favicon-16x16.png" sizes="16x16"><link rel="manifest" href="/img/favicons/manifest.json"><link rel="mask-icon" href="/img/favicons/safari-pinned-tab.svg" color="#e48632"><link rel="shortcut icon" href="/img/favicons/favicon.ico" type="image/x-icon"><meta name="msapplication-config" content="/img/favicons/browserconfig.xml"><meta name="theme-color" content="#e48632"><meta property="og:title" content="Contributing - Grunt: The JavaScript Task Runner"><meta property="og:type" content="website"><meta property="og:url" content="https://gruntjs.com/"><meta property="og:image" content="https://gruntjs.com/img/og.png"><meta property="og:image:type" content="image/png"><meta property="og:image:width" content="256"><meta property="og:image:height" content="256"><meta name="twitter:card" content="summary_large_image"><meta name="twitter:creator" content="@gruntjs"><meta name="twitter:site" content="@gruntjs"><meta name="twitter:title" content="Contributing - Grunt: The JavaScript Task Runner"><meta itemprop="name" content="Grunt"><meta itemprop="image" content="/img/og.png"><link href="/rss" rel="alternate" title="Grunt Blog Feed" type="application/atom+xml"></head><body class="page-docs page-secondary"><div class="banner"> <a href="support">V1.6.1 is the current version, and previous versions are not supported. Upgrade to the latest version or consider other support options.</a></div><div class="navbar navbar-inverse"><div class="navbar-inner"><div class="container"><a class="brand" href="/"><span class="logo"></span></a><div class="nav-collapse collapse"><ul class="nav"><li><a href="/getting-started"><i class="icon-arrow-right"></i><span>Getting Started</span></a></li><li><a href="/configuring-tasks"><i class="icon-cog"></i><span>Configuring Tasks</span></a></li><li><a href="/plugins"><i class="icon-power-cord"></i><span>Plugins</span></a></li><li><a href="/documentation"><i class="icon-file-text"></i><span>Documentation</span></a></li><li><a href="/support"><i class="icon-file-text"></i><span>Support</span></a></li></ul><form class="navbar-search pull-right"><input class="search-query" type="text" placeholder="Search"></form></div></div></div></div><div class="content"><div class="container contributing"><div class="row-fluid"><div class="span9 page"><div class="hero-unit"><h1>Contributing</h1><p>There are a number of Grunt projects.</p> <ul> <li><a href="https://github.com/gruntjs/grunt">grunt</a> - the main Grunt project</li> <li><a href="https://github.com/gruntjs/grunt-init">grunt-init</a> - the standalone grunt-init project scaffolding tool</li> <li><a href="https://github.com/gruntjs/gruntjs.com">gruntjs.com</a> - the gruntjs.com website</li> <li><a href="https://github.com/gruntjs/grunt-contrib">grunt-contrib collection</a> - a collection of all Grunt "contrib" plugins</li> </ul> <p>In addition, each individual grunt-contrib plugin is a separate repository listed on the <a href="https://github.com/gruntjs">gruntjs org homepage</a>. Each repository has its own maintainers, you can easily find the maintainers by looking at recent commits and pushes. Just create an issue in the repository that interests you and <code>@mention</code> one of the maintainers to get started.</p> <h2><a class="anchor" href="#contributors-license-agreement" id="contributors-license-agreement"></a>Contributors License Agreement</h2> <p>Most forms of contribution aside from providing support to other users requires that you <strong><a href="https://contribute.jquery.org/cla/">sign and submit</a></strong> a Contributors License Agreement (or "CLA" for short) with the jQuery Foundation.</p> <p>In summary, the CLA asserts that when you donate fixes or documentation, you both own the code that you're submitting and that the jQuery Foundation can in turn license that code to other people.</p> <p>Sending in a CLA is a one-time thing, and once it's done, you're in the clear to start contributing to all jQuery Foundation projects! To be effective, though, you need to know a little bit about how contributors and Committers coordinate their work, so getting involved and asking questions should be your first step.</p> <p>For more on CLAs, read <a href="https://infrequently.org/2008/06/why-do-i-need-to-sign-this/">Alex Russell's Why Do I Need to Sign This?</a>.</p> <h2><a class="anchor" href="#want-to-contribute" id="want-to-contribute"></a>Want to contribute?</h2> <p>If you want to contribute, but don't know where to get started, this is for you. Issues that are linked below were marked as <strong>needs PR</strong>, this means they need a pull request to be fixed. Choose any of these issues and make sure to comment if you are working on them.</p> <ul> <li>grunt-init - <a href="https://github.com/gruntjs/grunt-init/issues/5">Contribution guidelines should go into contributing.md</a></li> <li>grunt-contrib-jade - <a href="https://github.com/gruntjs/grunt-contrib-jade/issues/64">Add support for basedir option</a></li> <li>grunt-init-gruntfile - <a href="https://github.com/gruntjs/grunt-init-gruntfile/issues/6">Doesn't generate a package.json</a></li> <li>grunt-contrib-coffee - <a href="https://github.com/gruntjs/grunt-contrib-coffee/issues/61">Support the process option</a></li> <li>grunt - <a href="https://github.com/gruntjs/grunt/issues/950">--gruntfile parameter broken with parent directories</a></li> <li>grunt-contrib-compress - <a href="https://github.com/gruntjs/grunt-contrib-compress/issues/47">Add bzip2 support</a></li> <li>grunt-contrib-jasmine - <a href="https://github.com/gruntjs/grunt-contrib-jasmine/issues/80">Enhance logging</a></li> <li>grunt-contrib-less <a href="https://github.com/gruntjs/grunt-contrib-less/issues/89">Sourcemaps with multiple src files</a></li> </ul> <h2><a class="anchor" href="#publishing-a-new-version" id="publishing-a-new-version"></a>Publishing a new version</h2> <p>To publish a new version of a <code>grunt-contrib-*</code> plugin follow these steps:</p> <ul> <li>check the plugin GitHub page to make sure it is passing Travis CI.</li> <li><code>cd</code> into the plugin directory.</li> <li><code>git pull</code> the latest changes from the <code>master</code> branch.</li> <li><code>rm -rf node_modules</code> remove stale or old node modules.</li> <li><code>npm install</code> to get the latest version of the node modules.</li> <li>run <code>npm test</code> and make sure all tests pass locally.</li> <li>bump the version in <code>package.json</code></li> <li>update CHANGELOG.md</li> <li>run <code>grunt</code> in the plugin directory. This should generate the new README.</li> <li>commit the changelog, <code>package.json</code> and README changes.</li> <li>create a new git tag for the new version. use this format for the tag: <code>vX.Y.Z</code>. (such as <code>v0.1.13</code>)</li> <li>push changes to <code>master</code>, push tag to the plugin repo.</li> <li>Publish to npm: <code>npm publish .</code>. If you do not have access to <code>npm publish</code> ask one of the core contributors to publish for you.</li> </ul> <h1><a class="anchor" href="#non-code-contributions" id="non-code-contributions"></a>Non-code contributions</h1> <p>If you don't feel like writing code you can still contribute to the project!</p> <ul> <li>You may submit updates and improvements to the <a href="https://github.com/gruntjs/grunt-docs">documentation</a>.</li> <li>Submit articles and guides which are also part of the <a href="https://github.com/gruntjs/grunt-docs">documentation</a>.</li> <li>Help Grunt users by answering questions on <a href="https://stackoverflow.com/questions/tagged/gruntjs">StackOverflow</a>, <a href="https://gruntjs.com/help-resources#irc">IRC</a> and <a href="https://github.com/search?q=user%3Agruntjs&state=open&type=Issues&utf8=%E2%9C%93">GitHub</a>.</li> </ul> <h2><a class="anchor" href="#filing-issues" id="filing-issues"></a>Filing issues</h2> <p>If something isn't working like you think it should, please read <a href="https://github.com/gruntjs/grunt/wiki">the documentation</a>, especially the <a href="/getting-started/">Getting Started</a> guide. If you'd like to chat with someone, <a href="/contributing#discussing-grunt">pop into IRC</a> discussing-grunt and ask your question there.</p> <p>If you have a question not covered in the documentation or want to report a bug, the best way to ensure it gets addressed is to file it in the appropriate issues tracker.</p> <ul> <li><strong>If there's an issue with grunt, grunt-init, a grunt-lib-??? module, or a specific grunt-contrib-??? plugin</strong><ul> <li>Please file an issue on that project's issues tracker.</li> </ul> </li> <li><strong>If you'd like to contribute a new plugin</strong><ul> <li>Please file an issue on the <a href="https://github.com/gruntjs/grunt-contrib/issues">grunt-contrib collection issues tracker</a>. We don't accept all plugins, but we'll certainly consider yours.</li> </ul> </li> <li><strong>If there's an issue with the <a href="https://gruntjs.com/">website</a></strong><ul> <li>Please file an issue on the <a href="https://github.com/gruntjs/gruntjs.com/issues">gruntjs.com website issues tracker</a>.</li> </ul> </li> <li><strong>If there's an issue that isn't specific to any of the above</strong><ul> <li>Please file an issue on the <a href="https://github.com/gruntjs/grunt/issues">grunt issues tracker</a> and let us know why you're filing it there.</li> </ul> </li> </ul> <h3><a class="anchor" href="#simplify-the-issue" id="simplify-the-issue"></a>Simplify the issue</h3> <p>Try to <a href="http://www.webkit.org/quality/reduction.html">reduce your code</a> to the bare minimum required to reproduce the issue. This makes it much easier (and much faster) to isolate and fix the issue.</p> <h3><a class="anchor" href="#explain-the-issue" id="explain-the-issue"></a>Explain the issue</h3> <p>If we can't reproduce the issue, we can't fix it. Please list the exact steps required to reproduce the issue. Include versions of your OS, Node.js, grunt, etc. Include relevant logs or sample code.</p> <h2><a class="anchor" href="#discussing-grunt" id="discussing-grunt"></a>Discussing grunt</h2> <p>Join the <a href="http://freenode.net/">freenode</a>: IRC #grunt channel for general discussion or #grunt-dev for core and plugin development discussion. We've got a bot and everything.</p> <p><em>No private messages, please.</em></p> <h2><a class="anchor" href="#modifying-grunt" id="modifying-grunt"></a>Modifying grunt</h2> <p>First, ensure that you have the latest <a href="https://nodejs.org/">Node.js</a> and <a href="https://www.npmjs.com/">npm</a> installed.</p> <ol> <li>Ensure grunt-cli is installed (see the <a href="/getting-started/">Getting started</a> guide for more information)</li> <li>Fork and clone the repo.</li> <li>Check out the master branch (most grunt/grunt-contrib development happens there).</li> <li>Run <code>npm install</code> to install all Grunt dependencies.</li> <li>Run <code>npm uninstall grunt</code> this will remove the extra Grunt in your <code>node_modules</code>, see <a href="https://github.com/npm/npm/issues/3958">npm issue 3958</a></li> <li>Run <code>grunt</code> to Grunt grunt.</li> </ol> <p>Assuming that you don't see any red, you're ready to go. Just be sure to run <code>grunt</code> after making any changes, to ensure that nothing has broken.</p> <h3><a class="anchor" href="#submitting-pull-requests" id="submitting-pull-requests"></a>Submitting pull requests</h3> <ol> <li>Create a new branch, please don't work in <code>master</code> directly.</li> <li>Add failing tests for the change you want to make. Run <code>grunt</code> to see the tests fail.</li> <li>Fix stuff.</li> <li>Run <code>grunt</code> to see if the tests pass. Repeat steps 2-4 until done.</li> <li>Update the documentation to reflect any changes.</li> <li>Push to your fork and submit a pull request.</li> </ol> <h3><a class="anchor" href="#syntax" id="syntax"></a>Syntax</h3> <ul> <li>Two space indents. Don't use tabs anywhere. Use <code>\t</code> if you need a tab character in a string.</li> <li>No trailing whitespace, except in markdown files where a linebreak must be forced.</li> <li>Don't go overboard with the whitespace.</li> <li>No more than <a href="https://benalman.com/news/2012/05/multiple-var-statements-javascript/">one assignment</a> per <code>var</code> statement.</li> <li>Delimit strings with single-quotes <code>'</code>, not double-quotes <code>"</code>.</li> <li>Prefer <code>if</code> and <code>else</code> to <a href="https://softwareengineering.stackexchange.com/a/25281">"clever"</a> uses of <code>? :</code> conditional or <code>||</code>, <code>&&</code> logical operators.</li> <li>Comments are great. Just put them <em>before</em> the line of code, <em>not</em> at the <em>end</em> of the line.</li> <li><strong>When in doubt, follow the conventions you see used in the source already.</strong></li> </ul> <h3><a class="anchor" href="#readmes" id="readmes"></a>READMEs</h3> <p>All of the grunt-contrib-* plugins use <a href="https://github.com/gruntjs/grunt-contrib-internal">grunt-contrib-internal</a> to construct the <code>README.md</code> and <code>CONTRIBUTING.md</code> files. The source files are located in the corresponding <code>docs/</code> folder. The change logs in the READMEs are generated from the <code>CHANGELOG</code> file.</p> <p>When submitting changes to the README files please just edit the source files rather than the README directly.</p> <div class="end-link">Found an error in the documentation? <a href='https://github.com/gruntjs/grunt-docs/issues'>File an issue</a>.</div></div></div><div class="span3"><div class="well sidebar-nav"><ul class="nav nav-list"><li class="nav-header"><i class="icon-file-text"></i><span>Documentation</span></li><li><a href="/getting-started">Getting Started</a></li><li><a href="/configuring-tasks">Configuring Tasks</a></li><li><a href="/sample-gruntfile">Sample Gruntfile</a></li><li><a href="/creating-tasks">Creating Tasks</a></li><li><a href="/creating-plugins">Creating Plugins</a></li><li><a href="/using-the-cli">Using the CLI</a></li></ul><ul class="nav nav-list"><li class="nav-header"><span>Advanced</span></li><li><a href="/api">API</a></li><li><a href="/installing-grunt">Installing Grunt</a></li><li><a href="/frequently-asked-questions">Frequently Asked Questions</a></li><li><a href="/project-scaffolding">Project Scaffolding</a></li></ul><ul class="nav nav-list"><li class="nav-header"><span>Community</span></li><li><a href="/support">Support</a></li><li><a href="/help-resources">Help Resources</a></li><li><a href="/who-uses-grunt">Who uses Grunt</a></li><li><a href="/built-with-grunt-badge">Built with Grunt Badge</a></li><li><a class="active" href="/contributing">Contributing</a></li><li><a href="/development-team">Development Team</a></li></ul><ul class="nav nav-list"><li class="nav-header"><span>Migration guides</span></li><li><a href="/upgrading-from-0.3-to-0.4">Upgrading from 0.3 to 0.4</a></li><li><a href="/upgrading-from-0.4-to-1.0">Upgrading from 0.4 to 1.0</a></li></ul></div></div></div></div></div><footer class="grunt-footer"><div class="inner"><div class="container"><ul class="pull-right"><li><a href="/blog">Blog</a></li><li><a href="/upgrading-from-0.3-to-0.4">Migration Guides</a></li><li><a href="/contributing">Contributing</a></li><li><a href="/development-team">Development Team</a></li><li class="social"><a href="https://github.com/gruntjs/" title="Grunt on GitHub"><span class="icon-github"></span></a></li><li class="social"><a href="https://twitter.com/gruntjs/" title="Grunt on Twitter"><span class="icon-twitter"></span></a></li><li class="social"><a href="/rss" title="Grunt blog RSS feed"><span class="icon-rss"></span></a></li><li class="openjs"><a href="https://openjsf.org/" title="OpenJS Foundation"><img src="/img/openjsf-color-textw.svg" alt="OpenJS Foundation" width="100" height="31"></a></li></ul></div></div></footer></body></html>