Updated documentation with details on resolving Grails plugins via ma…

…ven repositories

resources/doc.properties

@@ -4,6 +4,7 @@ authors=Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown
 copyright=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.
 footer=Sponsored by <a href="http://springsource.com">SpringSource</a>
 # aliases are used in links to bind to a more specific topic name such as [GSP|guide:gsp]
+alias.mavendeploy=3.7.8 Deploying to a Maven Repository
 alias.dr=3.7 Dependency Resolution
 alias.ivy=3.7 Dependency Resolution
 alias.gsp=6.2 Groovy Server Pages

src/guide/12.2 Plugin Repositories.gdoc

@@ -1,6 +1,6 @@
-h4. Distributing Plugins in Grails Plugins Repository
+h4. Distributing Plugins in the Grails Central Plugins Repository
 
-The preferred way of plugin distributing is to publish it under Grails Plugins Repository. This will make your plugin visible to the [list-plugins|commandLine] command:
+The preferred way of plugin distribution is to publish your under Grails Plugins Repository. This will make your plugin visible to the [list-plugins|commandLine] command:
 
 {code:java}
 grails list-plugins
@@ -15,10 +15,10 @@ grails plugin-info [plugin-name]
 Which outputs more information based on the meta info entered into the plug-in descriptor. 
 
 {note}
-If you have created a Grails plug-in and want it to be hosted in the central repository take a look at the wiki page [http://grails.org/Creating+Plugins], which details how to go about releasing your plugin in the repository.
+If you have created a Grails plugin and want it to be hosted in the central repository take a look at the wiki page [http://grails.org/Creating+Plugins], which details how to go about releasing your plugin in the repository.
 {note}
 
-When you have access to the Grails Plug-in repository to release your plugin you simply have to execute the [release-plugin|commandLine] command:
+When you have access to the Grails Plugin repository to release your plugin you simply have to execute the [release-plugin|commandLine] command:
 
 {code:java}
 grails release-plugin
@@ -28,65 +28,74 @@ This will automatically commit changes to SVN, do some tagging and make your cha
 
 h4. Configuring Additional Repositories
 
-By default when you use the [list-plugins|commandLine], [install-plugin|commandLine] and [release-plugin|commandLine] command they work against the central repository hosted at http://plugins.grails.org.
+The way in which you configure repositories in Grails differs between Grails versions. For version of Grails 1.2 and earlier please refer to the [Grails 1.2 documentation|http://grails.org/doc/1.2.x/guide/12.%20Plug-ins.html#12.2%20Plugin%20Repositories] on the subject. The following sections cover Grails 1.3 and above.
 
-However, Grails supports the notion of multiple plugin repositories. To configure multiple repositories you can using the @grails-app/conf/BuildConfig.groovy@ file:
+Grails 1.3 and above use Ivy under the hood to resolve plugin dependencies. The mechanism for defining additional plugin repositories is largely the same as [defining repositories for JAR dependencies|guide:ivy]. For example you can define a remote Maven repository that contains Grails plugins using the following syntax in @grails-app/conf/BuildConfig.groovy@:
 
-{code:java}
-grails.plugin.repos.discovery.myRepository="http://svn.codehaus.org/grails/trunk/grails-test-plugin-repo" 
-grails.plugin.repos.distribution.myRepository="https://svn.codehaus.org/grails/trunk/grails-test-plugin-repo" 
+{code}
+repositories {
+	mavenRepo "http://repository.codehaus.org"
+}
 {code}
 
-Repositories are split into those used for discovery over HTTP and those used for distribution, typically over HTTPS. You can also provide these settings in the @USER_HOME/.grails/settings.groovy@ file if you prefer to share the same settings across multiple projects.
-
-Once this is done the [list-plugins|commandLine], [install-plugin|commandLine] and [plugin-info|commandLine] commands will automatically resolve against the newly configured repository. If you want to list only the plugins from the repository you can use its alias to do so:
+You can also defined a non-Maven Grails repository (such as the one hosted at http://plugins.grails.org/) using the @grailsRepo@ method:
 
-{code:java}
-grails list-plugins -repository=myRepository
+{code}
+repositories {
+	grailsRepo "http://myserver/mygrailsrepo"
+}
 {code}
 
-Additionally, if you want to distribute a plugin within the configured repository you can do so with the [release-plugin|commandLine] command:
+There is a shortcut to setup the Grails central repository:
 
-{code:java}
-grails release-plugin -repository=myRepository
+{code}
+repositories {
+	grailsCentral()
+}
 {code}
 
-h4. Secured Plugin Repositories
-
-By default when using a repository URL starting with the @https://@ protocol, Grails will prompt you for a username and password. If you prefer 
-not to get these prompts then you can specify the username and password to use in your @~/.grails/settings.groovy@ file as follows:
+The order in which plugins are resolved is based on the ordering of the repositories. So for example in this case the Grails central repository will be searched last:
 
 {code}
-grails.plugin.repos.discovery.myRepo="https://user01:password01@myserver.com"
+repositories {
+	grailsRepo "http://myserver/mygrailsrepo"
+	grailsCentral()
+}
 {code}
 
-The format is: 
+All of the above examples use HTTP, however you can specify any [Ivy resolver|http://ant.apache.org/ivy/history/latest-milestone/settings/resolvers.html] to resolve plugins with. Below is an example that uses an SSH resolver:
 
 {code}
-PROTOCOL://USERNAME:PASSWORD@SERVER
+def sshResolver = new SshResolver(user:"myuser", host:"myhost.com")
+sshResolver.addArtifactPattern("/path/to/repo/grails-[artifact]/tags/LATEST_RELEASE/grails-[artifact]-[revision].[ext]")
+sshResolver.latestStrategy = new org.apache.ivy.plugins.latest.LatestTimeStrategy()
+sshResolver.changingPattern = ".*SNAPSHOT"
+sshResolver.setCheckmodified(true)
 {code}
 
-With this set Grails will use the specified username and password rather than prompting you for one.
+The above example defines an artifact pattern which tells Ivy how to resolve a plugin zip file. For a more detailed explanation on Ivy patterns see the [relevant section|http://ant.apache.org/ivy/history/2.1.0/concept.html#patterns] in the Ivy user guide.
 
-h4. Configuring Repository Search Order
+h4. Publishing to Maven Compatible Repositories
 
-A common use case for having your own plugin repository is when you want to override or provide a modified version of an existing plugin within the central repository.
+In general it is recommended for Grails 1.3 and above to use standard Maven-style repositories to self host plugins. The benefits of doing so include the ability for existing tooling and repository managers to interpret the structure of a Maven repository. In addition Maven compatible repositories are not tied to SVN as Grails repositories are.
 
-However, by default Grails will search repository in a preset order. The repositories it will search are as follows:
+In order to publish a plugin to a Maven repository you need to use the Maven publisher plugin. Please refer to the section of the [Maven deployment|guide:mavendeploy] user guide on the subject.
 
-* @default@ - The default repository found at @http://plugins.grails.org@
-* @core@ - The repository for plugins provides by the framework (such as the hibernate plugin)
+h4. Publishing to Grails Compatible Repositories
 
-If you add an additional repository then Grails will search the repository you have defined last, meaning it is not possible to override a plugin in the central repository unless you change the search order. To change the repository search order you can do the following:
+To publish a Grails plugin to a Grails compatible repository you specify the @grails.plugin.repos.distribution.myRepository@ setting within the grails-app/conf/BuildConfig.groovy file:
 
 {code}
-grails.plugin.repos.resolveOrder=['myRepository','default','core']
+grails.plugin.repos.distribution.myRepository="https://svn.codehaus.org/grails/trunk/grails-test-plugin-repo"
 {code}
 
-In the above case the repository called @myRepository@ will be searched before the default one. In addition, if you remove the built in repositories from the list you can prevent Grails from searching these repositories at all:
+You can also provide this settings in the USER_HOME/.grails/settings.groovy file if you prefer to share the same settings across multiple projects.
+
+Once this is done you need to use the @repository@ argument of the @release-plugin@ command to specify the repository you want to release the plugin into:
 
 {code}
-grails.plugin.repos.resolveOrder=['myRepository']
+grails release-plugin -repository=myRepository
 {code}
 
-This is useful in a circumstance where you don't want Grails to perform any internet lookups when searching for plugins.
+
+

src/guide/2.2 Upgrading from previous versions of Grails.gdoc

@@ -1,4 +1,14 @@
-Although the Grails development team have tried to keep breakages to a minimum there are a number of items to consider when upgrading a Grails 1.0.x or 1.1.x application to Grails 1.2. The major changes are described in detail below.
+Although the Grails development team have tried to keep breakages to a minimum there are a number of items to consider when upgrading a Grails 1.0.x, 1.1.x, or 1.2.x applications to Grails 1.3. The major changes are described in detail below.
+
+h3. Upgrading from Grails 1.2.x
+
+h4. Plugin Repositories
+
+As of Grails 1.3, Grails no longer natively supports resolving plugins against secured SVN repositories. Grails 1.2 and below's plugin resolution mechanism has been replaced by one built on Ivy the upside of which is that you can now resolve Grails plugins against Maven repositories as well as regular Grails repositories.
+
+Ivy supports a much richer setter of repository resolvers for resolving plugins with, including support for Webdav, HTTP, SSH and FTP. See the section on [resolvers|http://ant.apache.org/ivy/history/trunk/settings/resolvers.html] in the Ivy docs for all the available options and the section of [plugin repositories|guide:repositories] in the user guide which explains how to configure additional resolvers.
+
+If you still need support for resolving plugins against secured SVN repositories then the [IvySvn|http://code.google.com/p/ivysvn/] project provides a set of Ivy resolvers for resolving against SVN repositories.
 
 h3. Upgrading from Grails 1.1.x
 

src/guide/3.7.8 Deploying to a Maven Repository.gdoc

@@ -0,0 +1,100 @@
+You can deploy a Grails project or plugin to a Maven repository using the [maven-publisher|http://grails.org/plugin/maven-publisher] plugin. 
+
+The plugin provides the ability to publish Grails projects and plugins to local and remote Maven repositories. There are two key additional targets added by the plugin:
+
+* *maven-install* - Installs a Grails project or plugin into your local Maven cache
+* *maven-deploy* - Deploys a Grails project or plugin to a remote Maven repository
+
+By default this plugin will automatically generate a valid @pom.xml@ for you unless a @pom.xml@ is already present in the root of the project, in which case this @pom.xml@ file will be used.
+
+h4. maven-install
+
+The @maven-install@ command will install the Grails project or plugin artifact into your local Maven cache:
+
+{code}
+grails maven-install
+{code}
+
+In the case of plugins, the plugin zip file will be installed, whilst for application the application WAR file will be installed.
+
+h4. maven-deploy
+
+The @maven-deploy@ command will deploy a Grails project or plugin into a remote Maven repository:
+
+{code}
+grails maven-deploy
+{code}
+
+It is assumed that you have specified the necessary @<distributionManagement>@ configuration within a @pom.xml@ or that you specify the @id@ of the remote repository to deploy to:
+
+{code}
+grails maven-deploy --repository=myRepo
+{code}
+
+The @repository@ argument specifies the 'id' for the repository. You need to configure the details of the repository specified by this 'id' within your @grails-app/conf/BuildConfig.groovy@ file or in your @USER_HOMER/.grails/settings.groovy@ file:
+
+{code}
+grails.project.dependency.distribution = {
+     localRepository = "/path/to/my/local"
+     remoteRepository(id:"myRepo", url:"http://myserver/path/to/repo")
+}
+{code}
+
+The syntax for configuring remote repositories matches the syntax from the [remoteRepository|http://maven.apache.org/ant-tasks/reference.html#remoteRepository] element in the Ant Maven tasks. For example the following XML:
+
+{code}
+   <remoteRepository id="myRepo" url="scp://localhost/www/repository">
+      <authentication username="..." privateKey="${user.home}/.ssh/id_dsa"/>
+    </remoteRepository>
+{code}
+
+Can be expressed as:
+
+{code}
+   remoteRepository(id:"myRepo", url:"scp://localhost/www/repository") {
+       authentication username:"...", privateKey:"${userHome}/.ssh/id_dsa"
+    }
+{code}
+
+By default the plugin will try to detect the protocol to use from the URL of the repository (ie "http" from "http://.." etc.), however if you need to explicitly specify a different protocol you can do:
+
+{code}
+grails maven-deploy --repository=myRepo --protocol=webdav
+{code}
+
+The available protocols are:
+
+* http
+* scp
+* scpexe
+* ftp
+* webdav
+
+h4. Groups, Artifacts and Versions
+
+Maven defines the notion of a 'groupId', 'artifactId' and a 'version'. This plugin pulls this information from the Grails project conventions or plugin descriptor.
+
+h5. Projects
+
+For applications this plugin will use the Grails application name and version provided by Grails when generating the @pom.xml@ file. To change the version you can run the @set-version@ command:
+
+{code}
+grails set-version 0.2
+{code}
+
+The Maven @groupId@ will be the same as the project name, unless you specify a different one in Config.groovy:
+
+{code}
+grails.project.groupId="com.mycompany" 
+{code}
+
+h5. Plugins
+
+With a Grails plugin the @groupId@ and @version@ are taken from the following properties in the *GrailsPlugin.groovy descriptor:
+
+{code}
+String groupId = 'myOrg'
+String version = '0.1'
+{code}
+
+The 'artifactId' is taken from the plugin name. For example if you have a plugin called @FeedsGrailsPlugin@ the @artifactId@ will be "feeds". If your plugin does not specify a @groupId@ then this defaults to "org.grails.plugins".

src/guide/3.7.9 Plugin Dependencies.gdoc

@@ -0,0 +1,27 @@
+As of Grails 1.3 you can declaratively specify dependencies on plugins rather than using the [install-plugin|commandLine] command:
+
+{code}
+plugins {
+	runtime ':hibernate:1.2.1'
+}
+{code}
+
+If you don't specify a group id the default plugin group id of @org.grails.plugins@ is used. You can specify to use the latest version of a particular plugin by using "latest.integration" as the version number:
+
+{code}
+plugins {
+	runtime ':hibernate:latest.integration'
+}
+{code}
+
+And of course if you are using a Maven repository with an alternative group id you can specify a group id:
+
+{code}
+plugins {
+	runtime 'mycompany:hibernate:latest.integration'
+}
+{code}
+
+
+
+