blob: 001cca5c5a780596eb8689f9e0db330504d4e7c6 [file]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<!-- Matomo -->
<script>
var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
_paq.push(["setDoNotTrack", true]);
_paq.push(["disableCookies"]);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="https://analytics.apache.org/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '79']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- End Matomo Code -->
<title>22 Contributing to Grails 5.3.6</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
<link rel="stylesheet" href="../css/pdf.css" type="text/css" media="print" title="PDF" charset="utf-8"/>
<script type="text/javascript">
function addJsClass() {
var classes = document.body.className.split(" ");
classes.push("js");
document.body.className = classes.join(" ");
}
</script>
</head>
<body class="body" onload="addJsClass();">
<div id="navigation">
<div class="navTitle">
The Grails Framework
</div>
<div class="navLinks">
<ul>
<li>
<div id="nav-summary" onmouseover="toggleNavSummary(false)" onmouseout="toggleNavSummary(true)">
<a href="../guide/index.html" class="button">Table of contents</a>
<div id="nav-summary-childs" style="display:none;">
<div class="toc-item" style="margin-left:0"><a href="../guide/introduction.html"><strong>1</strong><span>Introduction</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/gettingStarted.html"><strong>2</strong><span>Getting Started</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/upgrading.html"><strong>3</strong><span>Upgrading from the previous versions</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/conf.html"><strong>4</strong><span>Configuration</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/commandLine.html"><strong>5</strong><span>The Command Line</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/profiles.html"><strong>6</strong><span>Application Profiles</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/GORM.html"><strong>7</strong><span>Object Relational Mapping (GORM)</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/theWebLayer.html"><strong>8</strong><span>The Web Layer</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/traits.html"><strong>9</strong><span>Traits</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/REST.html"><strong>10</strong><span>REST</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/async.html"><strong>11</strong><span>Asynchronous Programming</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/validation.html"><strong>12</strong><span>Validation</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/services.html"><strong>13</strong><span>The Service Layer</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/staticTypeCheckingAndCompilation.html"><strong>14</strong><span>Static Type Checking And Compilation</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>15</strong><span>Testing</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/i18n.html"><strong>16</strong><span>Internationalization</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/security.html"><strong>17</strong><span>Security</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/plugins.html"><strong>18</strong><span>Plugins</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/spring.html"><strong>19</strong><span>Grails and Spring</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/scaffolding.html"><strong>20</strong><span>Scaffolding</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/deployment.html"><strong>21</strong><span>Deployment</span></a>
</div>
<div class="toc-item" style="margin-left:0"><a href="../guide/contributing.html"><strong>22</strong><span>Contributing to Grails</span></a>
</div>
</div>
</div>
</li>
<li class="separator selected">
<a id="ref-button" onclick="localToggle(); return false;" href="#">Quick Reference</a>
</li>
</ul>
</div>
</div>
<table id="colset" border="0" cellpadding="0" cellspacing="0">
<tr>
<td id="col1">
<div id="main" class="corner-all">
<div class="toc-item prev-left"><a href="../guide/deployment.html">&lt;&lt; <strong>21</strong><span>Deployment</span></a></div>
<span id='toggle-col1' class="toggle">(<a href="#" onclick="localToggle(); return false;">Quick Reference</a>)</span>
<div class="project">
<h1>22 Contributing to Grails</h1>
<p><strong>Version:</strong> 5.3.6</p>
</div>
<div id="table-of-content">
<h2>Table of Contents</h2>
<div class="toc-item" style="margin-left:0px"><a href="#issues"><strong>22.1</strong><span>Report Issues in Github's issue tracker</span></a>
</div>
<div class="toc-item" style="margin-left:0px"><a href="#build"><strong>22.2</strong><span>Build From Source and Run Tests</span></a>
</div>
<div class="toc-item" style="margin-left:0px"><a href="#patchesCore"><strong>22.3</strong><span>Submit Patches to Grails Core</span></a>
</div>
<div class="toc-item" style="margin-left:0px"><a href="#patchesDoc"><strong>22.4</strong><span>Submit Patches to Grails Documentation</span></a>
</div>
</div>
<h1 id="contributing">22 Contributing to Grails</h1>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/5.3.x/src/en/guide/contributing.adoc"'>
<i class='fa fa-pencil-square-o'></i> Improve this doc
</button>
</div>
<div class="paragraph">
<p>Grails is an open source project with an active community and we rely heavily on that community to help make Grails better. As such, there are various ways in which people can contribute to Grails. One of these is by <a href="plugins.html">writing useful plugins</a> and making them publicly available. In this chapter, we&#8217;ll look at some of the other options.</p>
</div>
<h2 id="issues">22.1 Report Issues in Github's issue tracker</h2>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/5.3.x/src/en/guide/contributing/issues.adoc"'>
<i class='fa fa-pencil-square-o'></i> Improve this doc
</button>
</div>
<div class="paragraph">
<p>Grails uses Github to track issues in the <a href="https://github.com/grails/grails-core/issues">core framework</a>. Similarly for its documentation there is a <a href="https://github.com/grails/grails-doc/issues">separate tracker</a>. If you&#8217;ve found a bug or wish to see a particular feature added, these are the places to start. You&#8217;ll need to create a (free) github account in order to either submit an issue or comment on an existing one in either of these.</p>
</div>
<div class="paragraph">
<p>When submitting issues, please provide as much information as possible and in the case of bugs, make sure you explain which versions of Groovy, Grails and various plugins you are using. Other environment details - OS version, JDK, Gradle etc. should also be included. Also, an issue is much more likely to be dealt with if you upload a reproducible sample application on a github repository and provide a link in the issue.</p>
</div>
<div class="sect2">
<h3 id="_reviewing_issues">Reviewing issues</h3>
<div class="paragraph">
<p>There are quite a few old issues in github, some of which may no longer be valid. The core team can&#8217;t track down these alone, so a very simple contribution that you can make is to verify one or two issues occasionally.</p>
</div>
<div class="paragraph">
<p>Which issues need verification? Going to the <a href="https://github.com/grails/grails-core/issues?q=is%3Aopen+is%3Aissue">issue tracker</a> will display all issues that haven&#8217;t been resolved.</p>
</div>
<div class="paragraph">
<p>Once you&#8217;ve verified an issue, simply add a short comment explaining what you found. Be sure to metion your environment details and grails version.</p>
</div>
</div>
<h2 id="build">22.2 Build From Source and Run Tests</h2>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/5.3.x/src/en/guide/contributing/build.adoc"'>
<i class='fa fa-pencil-square-o'></i> Improve this doc
</button>
</div>
<div class="paragraph">
<p>If you&#8217;re interested in contributing fixes and features to any part of grails, you will have to learn how to get hold of the project&#8217;s source, build it and test it with your own applications. Before you start, make sure you have:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A JDK (7 or above)</p>
</li>
<li>
<p>A git client</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Once you have all the pre-requisite packages installed, the next step is to download the Grails source code, which is hosted at <a href="http://github.com">GitHub</a> in several repositories owned by the <a href="http://github.com/grails">"grails" GitHub user</a>. This is a simple case of cloning the repository you&#8217;re interested in. For example, to get the core framework run:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">git clone <span class="key">http</span>:<span class="comment">//github.com/grails/grails-core.git</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This will create a "grails-core" directory in your current working directory containing all the project source files. The next step is to get a Grails installation from the source.</p>
</div>
<div class="sect2">
<h3 id="_creating_a_grails_installation">Creating a Grails installation</h3>
<div class="paragraph">
<p>If you look at the project structure, you&#8217;ll see that it doesn&#8217;t look much like a standard <code>GRAILS_HOME</code> installation. But, it&#8217;s very simple to turn it into one. Just run this from the root directory of the project:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">.<span class="regexp"><span class="delimiter">/</span><span class="content">gradlew install</span></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This will fetch all the standard dependencies required by Grails and then build a <code>GRAILS_HOME</code> installation. Note that this target skips the extensive collection of Grails test classes, which can take some time to complete.</p>
</div>
<div class="paragraph">
<p>Once the above command has finished, simply set the <code>GRAILS_HOME</code> environment variable to the checkout directory and add the "bin" directory to your path. When you next type <code>grails</code> command to run, you&#8217;ll be using the version you just built.</p>
</div>
<div class="paragraph">
<p>If you are using <a href="http://sdkman.io">SDKMAN</a> then that can also be used to work with this local installation via the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">sdk install grails dev /path/to/grails-core</code></pre>
</div>
</div>
<div class="paragraph">
<p>You will also need to publish your local installation to your local maven.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>./gradlew pTML</pre>
</div>
</div>
<div class="paragraph">
<p>Now you will have a dev version in your local which you can use to test your features.</p>
</div>
</div>
<div class="sect2">
<h3 id="_running_the_test_suite">Running the test suite</h3>
<div class="paragraph">
<p>All you have to do to run the full suite of tests is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">.<span class="regexp"><span class="delimiter">/</span><span class="content">gradlew test</span></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>These will take a while (15-30 mins), so consider running individual tests using the command line. For example, to run the test spec <code>BinaryPluginSpec</code> simply execute the following command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">.<span class="regexp"><span class="delimiter">/</span><span class="content">gradlew :grails-core:test --tests *.BinaryPluginSpec</span></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that you need to specify the sub-project that the test case resides in, because the top-level "test" target won&#8217;t work&#8230;&#8203;.</p>
</div>
</div>
<div class="sect2">
<h3 id="_developing_in_intellij_idea">Developing in IntelliJ IDEA</h3>
<div class="paragraph">
<p>You need to run the following gradle task:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">.<span class="regexp"><span class="delimiter">/</span><span class="content">gradlew idea</span></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Then open the project file which is generated in IDEA. Simple!</p>
</div>
</div>
<div class="sect2">
<h3 id="_developing_in_sts_eclipse">Developing in STS / Eclipse</h3>
<div class="paragraph">
<p>You need to run the following gradle task:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">.<span class="regexp"><span class="delimiter">/</span><span class="content">gradlew cleanEclipse eclipse</span></span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Before importing projects to STS do the following action:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Edit grails-scripts/.classpath and remove the line "&lt;classpathentry kind="src" path="../scripts"/&gt;".</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Use "Import&#8594;General&#8594;Existing Projects into Workspace" to import all projects to STS. There will be a few build errors. To fix them do the following:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Add the springloaded-core JAR file in $GRAILS_HOME/lib/org.springsource.springloaded/springloaded-core/jars to grails-core&#8217;s classpath.</p>
</li>
<li>
<p>Remove "src/test/groovy" from grails-plugin-testing&#8217;s source path GRECLIPSE-1067</p>
</li>
<li>
<p>Add the jsp-api JAR file in $GRAILS_HOME/lib/javax.servlet.jsp/jsp-api/jars to the classpath of grails-web</p>
</li>
<li>
<p>Fix the source path of grails-scripts. Add linked source folder linking to "../scripts". If you get build errors in grails-scripts, do "../gradlew cleanEclipse eclipse" in that directory and edit the .classpath file again (remove the line "&lt;classpathentry kind="src" path="../scripts"/&gt;"). Remove possible empty "scripts" directory under grails-scripts if you are not able to add the linked folder.</p>
</li>
<li>
<p>Do a clean build for the whole workspace.</p>
</li>
<li>
<p>To use Eclipse GIT scm team provider: Select all projects (except "Servers") in the navigation and right click &#8594; Team &#8594; Share project (not "Share projects"). Choose "Git". Then check "Use or create repository in parent folder of project" and click "Finish".</p>
</li>
<li>
<p>Get the recommended code style settings from the <a href="http://grails.1312388.n4.nabble.com/Grails-development-code-style-IDE-formatting-settings-tp3854216p3854216.html">mailing list thread</a> (final style not decided yet, currently <a href="http://grails.1312388.n4.nabble.com/attachment/3854262/0/profile.xml">profile.xml</a>). Import the code style xml file to STS in Window&#8594;Preferences&#8594;Java&#8594;Code Style&#8594;Formatter&#8594;Import . Grails code uses spaces instead of tabs for indenting.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_debugging_grails_or_a_grails_application">Debugging Grails or a Grails application</h3>
<div class="paragraph">
<p>To enable debugging, run:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">grails run-app --debug-jvm</code></pre>
</div>
</div>
<div class="paragraph">
<p>By default Grails forks a JVM to run the application in. The <code>-debug-jvm</code> argument causes the debugger to be associated with the forked JVM. In order to instead attach the debugger to the build system which is going to fork the JVM use the <code>-debug</code> option:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">grails -debug run-app</code></pre>
</div>
</div>
</div>
<h2 id="patchesCore">22.3 Submit Patches to Grails Core</h2>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/5.3.x/src/en/guide/contributing/patchesCore.adoc"'>
<i class='fa fa-pencil-square-o'></i> Improve this doc
</button>
</div>
<div class="paragraph">
<p>If you want to submit patches to the project, you simply need to fork the repository on GitHub rather than clone it directly. Then you will commit your changes to your fork and send a pull request for a core team member to review.</p>
</div>
<div class="sect2">
<h3 id="_forking_and_pull_requests">Forking and Pull Requests</h3>
<div class="paragraph">
<p>One of the benefits of <a href="http://github.com">GitHub</a> is the way that you can easily contribute to a project by <a href="https://help.github.com/articles/fork-a-repo/">forking the repository</a> and <a href="https://help.github.com/articles/creating-a-pull-request/">sending pull requests</a> with your changes.</p>
</div>
<div class="paragraph">
<p>What follows are some guidelines to help ensure that your pull requests are speedily dealt with and provide the information we need. They will also make your life easier!</p>
</div>
<div class="sect3">
<h4 id="_make_sure_your_fork_is_up_to_date">Make sure your fork is up to date</h4>
<div class="paragraph">
<p>Making changes to outdated sources is not a good idea. Someone else may have already made the change.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">git pull upstream master</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_create_a_local_branch_for_your_changes">Create a local branch for your changes</h4>
<div class="paragraph">
<p>Your life will be greatly simplified if you create a local branch to make your changes on. For example, as soon as you fork a repository and clone the fork locally, execute</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">git checkout -b issue_123</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will create a new local branch called "issue_123" based off the "master" branch. Of course, you can name the branch whatever you like, but a good idea would be to reference the GitHub issue number that the change is relevant to. Each Pull Request should have its own branch.</p>
</div>
</div>
<div class="sect3">
<h4 id="_create_github_issues_for_non_trivial_changes">Create Github issues for non-trivial changes</h4>
<div class="paragraph">
<p>For any non-trivial changes, raise an issue on github if one doesn&#8217;t already exist. That helps us keep track of what changes go into each new version of Grails.</p>
</div>
</div>
<div class="sect3">
<h4 id="_include_github_issue_id_in_commit_messages">Include github issue ID in commit messages</h4>
<div class="paragraph">
<p>This may not seem particularly important, but having a github issue ID in a commit message means that we can find out at a later date why a change was made. Include the ID in any and all commits that relate to that issue. If a commit isn&#8217;t related to an issue, then there&#8217;s no need to include an issue ID.</p>
</div>
</div>
<div class="sect3">
<h4 id="_make_sure_your_fork_is_up_to_date_again_and_rebase">Make sure your fork is up to date again and rebase</h4>
<div class="paragraph">
<p>Since the core developers must merge your commits into the main repository, it makes life much easier if your fork on GitHub is up to date before you send a pull request.</p>
</div>
<div class="paragraph">
<p>Let&#8217;s say you have the main repository set up as a remote called "upstream" and you want to submit a pull request. Also, all your changes are currently on the local "issue_123" branch but not on "master". The first step involves pulling any changes from the main repository that have been added since you last fetched and merged:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">git checkout master
git pull upstream master</code></pre>
</div>
</div>
<div class="paragraph">
<p>This should complete without any problems or conflicts. Next, rebase your local branch against the now up-to-date master:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">git checkout issue_123
git rebase master</code></pre>
</div>
</div>
<div class="paragraph">
<p>What this does is rearrange the commits such that all of your changes come after the most recent one in master. Think adding some cards to the top of a deck rather than shuffling them into the pack.</p>
</div>
</div>
<div class="sect3">
<h4 id="_push_your_branch_to_github_and_send_pull_request">Push your branch to GitHub and send Pull Request</h4>
<div class="paragraph">
<p>Finally, you must push your changes to your fork on GitHub, otherwise the core developers won&#8217;t be able to pick them up:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy">git push origin issue_123</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
You should not merge your branch to your forks master. If the Pull Request is not accepted, your master will then be out of sync with upstream forever.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>You&#8217;re now ready to send the pull request from the GitHub user interface.</p>
</div>
</div>
<div class="sect3">
<h4 id="_say_what_your_pull_request_is_for">Say what your pull request is for</h4>
<div class="paragraph">
<p>A pull request can contain any number of commits and it may be related to any number of issues. In the pull request message, please specify the IDs of all issues that the request relates to. Also give a brief description of the work you have done, such as: "I refactored the data binder and added support for custom number editors. Fixes #xxxx".</p>
</div>
</div>
</div>
<h2 id="patchesDoc">22.4 Submit Patches to Grails Documentation</h2>
<div class='contribute-btn'>
<button type='button' class='btn btn-default' onclick='window.location.href="https://github.com/grails/grails-doc/edit/5.3.x/src/en/guide/contributing/patchesDoc.adoc"'>
<i class='fa fa-pencil-square-o'></i> Improve this doc
</button>
</div>
<div class="sect2">
<h3 id="_contributing_simple_changes">Contributing Simple Changes</h3>
<div class="paragraph">
<p>The user guide is written using <a href="http://asciidoctor.org/docs/user-manual/">Asciidoctor</a>. The simplest way to contribute fixes is to simply click on the "Improve this doc" link that is to the right of each section of the documentation.</p>
</div>
<div class="paragraph">
<p>This will link to the Github edit screen where you can make changes, preview them and create a pull request.</p>
</div>
</div>
<div class="sect2">
<h3 id="_building_the_guide">Building the Guide</h3>
<div class="paragraph">
<p>If you want to make significant changes, such as changing the structure of the table of contents etc. then we recommend you build the user guide. To do that simply checkout the sources from github:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ git clone https://github.com/grails/grails-doc/
$ cd grails-doc</code></pre>
</div>
</div>
<div class="paragraph">
<p>The source files can be found in the <code>src/en/guide</code> directory. Whilst the Table of Contents (TOC) is defined in the <code>src/en/guide/toc.yml</code> file.</p>
</div>
<div class="paragraph">
<p>Each YAML key points to a Asciidoc template. For example consider the following YAML:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="yaml"><span class="key">introduction</span>:
<span class="key">title</span>: <span class="string"><span class="content">Introduction</span></span>
<span class="key">whatsNew</span>:
<span class="key">title</span>: <span class="string"><span class="content">What's new in Grails 3.2?</span></span>
<span class="error">...</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>introduction</code> key points to <code>src/en/guide/introduction.adoc</code>. The <code>title</code> key defines the title that is dislayed in the TOC. Because <code>whatsNew</code> key is nested underneath the <code>introduction</code> key it points to <code>src/en/guide/introduction/whatsNew.adoc</code>, which is nested in a directory called <code>introduction</code>.</p>
</div>
<div class="paragraph">
<p>Essentially, using the <code>toc.yml</code> file and the directory structure you can manipulate the structure of the user guide.</p>
</div>
<div class="paragraph">
<p>To generate the documentation run the <code>publishGuide</code> task:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ ./gradlew publishGuide -x apiDocs</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
In the above example we skip the <code>apiDocs</code> task to speed up building of the guide, otherwise all Groovydoc documentation will be built too!
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Once the guide is built simply open the <code>build/docs/index.html</code> file in a browser to review your changes.</p>
</div>
</div>
<div style="clear:both;margin-top:15px;"></div>
<div class="toc-item prev-left"><a href="../guide/deployment.html">&lt;&lt; <strong>21</strong><span>Deployment</span></a></div>
<div style="clear:both"></div>
</div>
</td>
<td id="col2">
<div class="local clearfix">
<div class="local-title">
<a href="../guide/index.html" target="mainFrame">Quick Reference</a>
<span class="toggle">(<a href="#" onclick="localToggle(); return false;">hide</a>)</span>
</div>
<div class="menu">
<div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Command Line</h1><div class="menu-sub">
<div class="menu-item"><a href="../ref/Command%20Line/Usage.html">Usage</a></div>
<div class="menu-item"><a href="../ref/Command%20Line/bug-report.html">bug-report</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/clean.html">clean</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/compile.html">compile</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/console.html">console</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-app.html">create-app</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-command.html">create-command</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-controller.html">create-controller</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-domain-class.html">create-domain-class</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-functional-test.html">create-functional-test</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-hibernate-cfg-xml.html">create-hibernate-cfg-xml</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-integration-test.html">create-integration-test</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-interceptor.html">create-interceptor</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-plugin.html">create-plugin</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-profile.html">create-profile</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-script.html">create-script</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-service.html">create-service</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-taglib.html">create-taglib</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/create-unit-test.html">create-unit-test</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/dependency-report.html">dependency-report</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/docs.html">docs</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/generate-all.html">generate-all</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/generate-controller.html">generate-controller</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/generate-views.html">generate-views</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/help.html">help</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/install-templates.html">install-templates</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/list-plugins.html">list-plugins</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/list-profiles.html">list-profiles</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/package-plugin.html">package-plugin</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/package.html">package</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/plugin-info.html">plugin-info</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/profile-info.html">profile-info</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/run-app.html">run-app</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/run-command.html">run-command</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/run-script.html">run-script</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/schema-export.html">schema-export</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/shell.html">shell</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/stats.html">stats</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/stop-app.html">stop-app</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/test-app.html">test-app</a>
</div>
<div class="menu-item"><a href="../ref/Command%20Line/war.html">war</a>
</div>
</div>
</div>
<div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Constraints</h1><div class="menu-sub">
<div class="menu-item"><a href="../ref/Constraints/Usage.html">Usage</a></div>
<div class="menu-item"><a href="../ref/Constraints/attributes.html">attributes</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/bindable.html">bindable</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/blank.html">blank</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/creditCard.html">creditCard</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/email.html">email</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/inList.html">inList</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/matches.html">matches</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/max.html">max</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/maxSize.html">maxSize</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/min.html">min</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/minSize.html">minSize</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/notEqual.html">notEqual</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/nullable.html">nullable</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/range.html">range</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/scale.html">scale</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/size.html">size</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/unique.html">unique</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/url.html">url</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/validator.html">validator</a>
</div>
<div class="menu-item"><a href="../ref/Constraints/widget.html">widget</a>
</div>
</div>
</div>
<div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Controllers</h1><div class="menu-sub">
<div class="menu-item"><a href="../ref/Controllers/Usage.html">Usage</a></div>
<div class="menu-item"><a href="../ref/Controllers/actionName.html">actionName</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/allowedMethods.html">allowedMethods</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/bindData.html">bindData</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/chain.html">chain</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/controllerName.html">controllerName</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/defaultAction.html">defaultAction</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/errors.html">errors</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/flash.html">flash</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/forward.html">forward</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/grailsApplication.html">grailsApplication</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/hasErrors.html">hasErrors</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/header.html">header</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/namespace.html">namespace</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/params.html">params</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/redirect.html">redirect</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/render.html">render</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/request.html">request</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/respond.html">respond</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/response.html">response</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/responseFormats.html">responseFormats</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/scope.html">scope</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/servletContext.html">servletContext</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/session.html">session</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/withForm.html">withForm</a>
</div>
<div class="menu-item"><a href="../ref/Controllers/withFormat.html">withFormat</a>
</div>
</div>
</div>
<div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Database Mapping</h1><div class="menu-sub">
<div class="menu-item"><a href="../ref/Database%20Mapping/Usage.html">Usage</a></div>
<div class="menu-item"><a href="../ref/Database%20Mapping/autoImport.html">autoImport</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/autoTimestamp.html">autoTimestamp</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/batchSize.html">batchSize</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/cache.html">cache</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/cascade.html">cascade</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/column.html">column</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/comment.html">comment</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/discriminator.html">discriminator</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/dynamicInsert.html">dynamicInsert</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/dynamicUpdate.html">dynamicUpdate</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/fetch.html">fetch</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/id.html">id</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/ignoreNotFound.html">ignoreNotFound</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/indexColumn.html">indexColumn</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/insertable.html">insertable</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/joinTable.html">joinTable</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/lazy.html">lazy</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/order.html">order</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/sort.html">sort</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/table.html">table</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/type.html">type</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/updateable.html">updateable</a>
</div>
<div class="menu-item"><a href="../ref/Database%20Mapping/version.html">version</a>
</div>
</div>
</div>
<div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Domain Classes</h1><div class="menu-sub">
<div class="menu-item"><a href="../ref/Domain%20Classes/Usage.html">Usage</a></div>
<div class="menu-item"><a href="../ref/Domain%20Classes/addTo.html">addTo</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/attach.html">attach</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/belongsTo.html">belongsTo</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/clearErrors.html">clearErrors</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/constraints.html">constraints</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/count.html">count</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/countBy.html">countBy</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/createCriteria.html">createCriteria</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/delete.html">delete</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/discard.html">discard</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/embedded.html">embedded</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/errors.html">errors</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/executeQuery.html">executeQuery</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/executeUpdate.html">executeUpdate</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/exists.html">exists</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/fetchMode.html">fetchMode</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/find.html">find</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/findAll.html">findAll</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/findAllBy.html">findAllBy</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/findAllWhere.html">findAllWhere</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/findBy.html">findBy</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/findOrCreateBy.html">findOrCreateBy</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/findOrCreateWhere.html">findOrCreateWhere</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/findOrSaveBy.html">findOrSaveBy</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/findOrSaveWhere.html">findOrSaveWhere</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/findWhere.html">findWhere</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/first.html">first</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/get.html">get</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/getAll.html">getAll</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/getDirtyPropertyNames.html">getDirtyPropertyNames</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/getPersistentValue.html">getPersistentValue</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/hasErrors.html">hasErrors</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/hasMany.html">hasMany</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/hasOne.html">hasOne</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/ident.html">ident</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/instanceOf.html">instanceOf</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/isAttached.html">isAttached</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/isDirty.html">isDirty</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/last.html">last</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/list.html">list</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/listOrderBy.html">listOrderBy</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/load.html">load</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/lock.html">lock</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/mapWith.html">mapWith</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/mappedBy.html">mappedBy</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/mapping.html">mapping</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/merge.html">merge</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/namedQueries.html">namedQueries</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/properties.html">properties</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/read.html">read</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/refresh.html">refresh</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/removeFrom.html">removeFrom</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/save.html">save</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/transients.html">transients</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/validate.html">validate</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/where.html">where</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/whereAny.html">whereAny</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/withCriteria.html">withCriteria</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/withNewSession.html">withNewSession</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/withSession.html">withSession</a>
</div>
<div class="menu-item"><a href="../ref/Domain%20Classes/withTransaction.html">withTransaction</a>
</div>
</div>
</div>
<div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Plug-ins</h1><div class="menu-sub">
<div class="menu-item"><a href="../ref/Plug-ins/Usage.html">Usage</a></div>
<div class="menu-item"><a href="../ref/Plug-ins/URL%20mappings.html">URL mappings</a>
</div>
<div class="menu-item"><a href="../ref/Plug-ins/codecs.html">codecs</a>
</div>
<div class="menu-item"><a href="../ref/Plug-ins/controllers.html">controllers</a>
</div>
<div class="menu-item"><a href="../ref/Plug-ins/core.html">core</a>
</div>
<div class="menu-item"><a href="../ref/Plug-ins/dataSource.html">dataSource</a>
</div>
<div class="menu-item"><a href="../ref/Plug-ins/domainClasses.html">domainClasses</a>
</div>
<div class="menu-item"><a href="../ref/Plug-ins/hibernate.html">hibernate</a>
</div>
<div class="menu-item"><a href="../ref/Plug-ins/i18n.html">i18n</a>
</div>
<div class="menu-item"><a href="../ref/Plug-ins/logging.html">logging</a>
</div>
<div class="menu-item"><a href="../ref/Plug-ins/scaffolding.html">scaffolding</a>
</div>
<div class="menu-item"><a href="../ref/Plug-ins/services.html">services</a>
</div>
<div class="menu-item"><a href="../ref/Plug-ins/servlets.html">servlets</a>
</div>
</div>
</div>
<div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Services</h1><div class="menu-sub">
<div class="menu-item"><a href="../ref/Services/Usage.html">Usage</a></div>
<div class="menu-item"><a href="../ref/Services/scope.html">scope</a>
</div>
</div>
</div>
<div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Servlet API</h1><div class="menu-sub">
<div class="menu-item"><a href="../ref/Servlet%20API/request.html">request</a>
</div>
<div class="menu-item"><a href="../ref/Servlet%20API/response.html">response</a>
</div>
<div class="menu-item"><a href="../ref/Servlet%20API/servletContext.html">servletContext</a>
</div>
<div class="menu-item"><a href="../ref/Servlet%20API/session.html">session</a>
</div>
</div>
</div>
</div>
</div>
</td>
</tr>
</table>
<div id="footer">
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
</div>
<script type="text/javascript" src="../js/docs.js"></script>
</body>
</html>