Split up the documentation into smaller files

doc/examples.md

@@ -0,0 +1,131 @@
+Examples
+--------
+
+There are a few things to keep in mind when setting up the `liquibase` block:
+
+1. We only need one activity block for each type of activity.  In the example below, the database
+   credentials are driven by build properties so that the correct database can be specified at build
+   time so that you don't need a separate activity for each database.
+
+2. By making the value of `runList` a property, you can determine the activities that get run at
+   build time.  For example, if you didn't need to run the security updates in the CI environment,
+   you could type `gradle update -PrunList=main` For environments where you do need the security
+   updates, you would use `gradle update -PrunList='main,security'`.  To do a diff, you'd run
+   `gradle diff -PrunList=diffMain`.  This use of properties is the reason the runList is a string
+   and not an array.
+
+3. The methods in each activity block are meant to be pass-throughs to Liquibase.  Any valid
+   Liquibase command parameter is a legal method here.  The command parameters are parameters in the
+   Liquibase documentation that start with a `--` such as `--difftypes` or `--logLevel`.  For
+   example, if you wanted to increase the log level, you could add `logLevel 'debug'` to the
+   activity.
+
+4. In addition to the command pass-through methods of an activity, there is a `changeLogParameters`
+   method.  This method takes a map, and is used to set up token substitution in the changeLogs.  See
+   the Liquibase documentation for more details on token substitution.
+
+5. Some Liquibase commands like `tag` and `rollback` require a value, in this case a tag name.  
+   Since the value will likely change from run to run, the command value is not configured in the
+   `liquibase` block.  To supply a command value, add `-PliquibaseCommandValue=<value>` to the
+   gradle command.
+
+Here are a few examples of `liquibase` blocks in the build.gradle file.
+
+[Example 1](#example1): The simple example.
+[Example 2](#example2): Multiple activities.
+
+### Example1
+
+A simple example might look like this:
+
+This example will work for many, if not most projects.  It defines the parameters that all commands
+will need, such as username and password, and there is only one activity.
+
+<details open>
+<summary><b>Groovy</b></summary>
+
+```groovy
+liquibase {
+  activities {
+    main {
+      changelogFile 'src/main/db/main.groovy'
+      url project.ext.mainUrl
+      username project.ext.mainUsername
+      password project.ext.mainPassword
+      logLevel "info"
+    }
+  }
+}
+```
+
+</details>
+<details>
+<summary><b>Kotlin</b></summary>
+
+Coming Soon
+</details>
+
+
+### Example2
+
+The plugin allows you to be much more complex if your situation requires it.
+
+Let's suppose that for each deployment, you need to update the data model for your application's
+database, and you also need to run some SQL statements in a separate database used for security.  
+Additionally, you want to occasionally run a diff between the changelog and the database.  The
+`liquibase` block might look like this:
+
+<details open>
+<summary><b>Groovy</b></summary>
+
+```groovy
+liquibase {
+  activities {
+    main {
+      changelogFile 'src/main/db/main.groovy'
+      url project.ext.mainUrl
+      username project.ext.mainUsername
+      password project.ext.mainPassword
+      logLevel "info"
+    }
+    security {
+      changelogFile 'src/main/db/security.groovy'
+      url project.ext.securityUrl
+      username project.ext.securityUsername
+      password project.ext.securityPassword
+      logLevel "info"
+    }
+    diffMain {
+      changelogFile 'src/main/db/main.groovy'
+      url project.ext.mainUrl
+      username project.ext.mainUsername
+      password project.ext.mainPassword
+      difftypes 'data'
+      logLevel "info"
+    }
+  }
+  runList = project.ext.runList
+}
+```
+
+</details>
+<details>
+<summary><b>Kotlin</b></summary>
+
+Coming Soon
+</details>
+
+
+If you want to use a different entry point than the default 
+`liquibase.integration.commandline.Main`, you can configure a different main class. This is
+useful if you want, for instance, to derive certain company-specific parameters.
+
+```groovy
+liquibase {
+  mainClassName 'liquibase.ext.commandline.LiquibaseAlternativeMain'
+}
+```
+
+For an example of how to configure and use this plugin, see the
+[Liquibase Workshop](https://github.com/stevesaliman/liquibase-workshop) repo. That project contains
+a `build.gradle` showing exactly how to configure the plugin, and an example directory setup as well.

doc/how-it-works.md

@@ -0,0 +1,48 @@
+How it works
+------------
+
+The Liquibase plugin is meant to be a light-weight front end for the Liquibase command line utility.
+When this plugin is applied, it creates a Gradle task for each command supported by Liquibase.
+`gradle tasks` will list out these tasks.  The
+[Liquibase Documentation](http://www.liquibase.org/documentation/command_line.html) describes what
+each command does and what parameters each command uses.  If you want to prefix each task to avoid
+task name conflicts, set a value for the `liquibaseTaskPrefix` property.  This will tell the
+liquibase plugin to capitalize the task name and prefix it with the given prefix.  For example, if
+you put `liquibaseTaskPrefix=liquibase` in `gradle.properties`, then this plugin will create tasks
+named `liquibaseUpdate`, `liquibaseTag`, etc.
+
+The Liquibase plugin has some subtle differences from the Liquibase command line utility.
+
+1. The liquibase `dbDoc` command has no default for the output directory, but the plugin does.  If
+   no value is given to this command, the plugin will put it in `{buildDir}/database/docs`.
+
+2. Some tasks like `updateSql` produce output.  Users of the plugin have 3 options for specifying
+   how those tasks work
+    1. With no configuration, the output will simply go to STDOUT.
+    2. If the activity has an `outputFile` method, it will use that file for all tasks that support
+       output files.
+    3. Users can specify `-PliquibaseOutputFile=myFile` to send output to a specific file.  If
+       specified, this command line option always wins.
+
+3. The Liquibase `execute-sql` command works with either SQL strings or SQL files.  The `executeSql`
+   task only supports SQL strings.  The plugin creates an `executeSqlFile` task for running SQL
+   files.  Under the covers, they run the same `execute-sql` command.
+
+When running a Liquibase task, Liquibase will parse changesets using any Liquibase parser that is in
+the classpath when Liquibase runs.  Some parsers, such as the XML parser and the YAML parser, are
+part of Liquibase itself, although some parsers require you to add additional dependencies to the
+liquibase classpath.  For example, the YAML parser requires `org.yaml:snakeyaml:1.17`.  Using this
+plugin with Liquibase 4.4.0+ also requires the `info.picocli:picocli:4.6.1` library.
+
+One of the best ways to parse Liquibase changesets is with the Groovy DSL, which is a much nicer way
+to write changelogs, especially since Groovy is the language of Gradle scripts themselves.  The
+Groovy DSL syntax intended to mirror the Liquibase XML syntax directly, such that mapping elements
+and attributes from the Liquibase documentation to Groovy builder syntax will result in a valid
+changelog. Hence, this DSL is not documented separately from the Liquibase XML format.  However,
+there are some minor differences or enhancements to the XML format, and there are some gaping holes
+in Liquibase's documentation of the XML. Those holes are filled, and differences explained in the
+documentation on the [Groovy Liquibase DSL](https://github.com/liquibase/liquibase-groovy-dsl)
+project page.  To use the Groovy DSL, simply include the Groovy DSL as a liquibaseRuntime dependency
+and specify a `changeLogFile` that ends in .groovy.  For those who, for some reason, still prefer
+XML, JSON, or Yaml, you can use these formats by specifying a `changeLogFile` that ends in the
+appropriate extension, and Liquibase will find and use the correct parser.

doc/releases.md

@@ -0,0 +1,69 @@
+Releases
+--------
+
+**IMPORTANT:** As of version 2.2.0, this plugin no longer works with Gradle versions prior to 6.4.
+
+**IMPORTANT:** Using version 2.1.0+ of this plugin with Liquibase 4.4.0+ requires additional 
+configuration.  Liquibase now uses the picocli library to parse options, but for some reason that
+library isn't a transitive dependency of Liquibase itself, so if you want to use this plugin with
+Liquibase 4.4.0+, you'll have to add the `liquibaseRuntime 'info.picocli:picocli:4.6.1'` dependency
+to your build.gradle file.
+
+This page gives the highlights newer releases.  For complete details of each release, including 
+older releases, see the [changelog](./changelog.md).
+
+### Release 2.2.0 (March 4, 2023)
+
+**Release 2.2.0 has some important and potentially breaking changes.**
+
+- Gradle 8 is supported, versions prior to 6.4 are no longer supported.
+
+- The older plugin id is no longer supported.  To apply this plugin now, you must use  
+  `org.liquibase.gradle`.
+
+- The plugin creates tasks that line up with the newer Liquibase 4.4+ commands.  To create tasks
+  that match the older pre 4.4 commands, to support backwards compatibility in CI/CD pipelines for
+  example, simply add `-PliquibaseCreateLegacyTasks` to the gradle command.  This can be done
+  regardless of the version of Liquibase being used.  This support will be removed in the future.
+  It is helpful to keep in mind that while it is convenient for the task to match the Liquibase
+  commands, it is not necessary, so Liquibase 4.4 tasks can still be used with older versions of
+  Liquibase, the plugin will translate commands and arguments automatically.
+
+- There is a new `executeSqlFile` task for executing SQL from a file.  The `executeSql` task now
+  only executes the SQL given in the `liquibaseCommandValue` property, and `executeSqlFile` executes
+  the SQL given in the filename specified by the `liquibaseCommandValue` property.
+
+- The plugin now sends the newer kebab case commands to Liquibase when it detects newer versions in
+  of Liquibase in the classpath.  For example, it uses `drop-all` when it detects version 4.4+
+  instead of the legacy `dropAll` command that it sends to older versions of Liquibase.
+
+- An output file can be specified on the command line, for tasks that use one, with the
+  `-PliquibaseOutputFile=someFile` property.  This will override the `outputFile` specified in the
+  `activity` block of your build.gradle file.
+
+- There is a new `-PliquibaseExtraArguments` property that can be used to override the arguments
+  that the plugin sends to Liquibase.
+
+### Release 2.1.1 (December 20, 2021)
+
+Fixed the Code that detects the version of liquibase in use at the time the liquibase tasks run.
+
+### Release 2.1.0 (November 13, 2021)
+
+Release 2.1.0 adds support for Liquibase 4.4.0 and 4.5.0. Liquibase 4.4.0 made extensive changes to
+the way it processes command line arguments.  Liquibase now uses the picocli library to parse
+options, but for some reason that library isn't a transitive dependency of Liquibase itself, so if
+you want to use this plugin with Liquibase 4.4.0+, you'll have to add the
+`liquibaseRuntime 'info.picocli:picocli:4.6.1'` dependency to your build.gradle file.
+
+Liquibase now has 2 "Main" classes and this plugin chooses the best one based on the version of
+Liquibase it detects.  You can still set a mainClassName, in the liquibase block of your
+build.gradle file, but it will most likely fail in Liquibase 4.4+.
+
+There is also a subtle change in the way "SQL" tasks get created.  Tasks that ended with "SQL" now
+end with "Sql".  For example `updateSQL` is now `updateSql`.  Since neither Gradle nor Liquibase
+seems to pay too much attention to case, this should not cause any breaking changes for now, but as
+Liquibase itself transitions from camelCase commands to kebab case commands, this may become
+important in the future, and this change will make it easier to pass the right thing to Liquibase if
+and when Liquibase ever stops supporting camel case.
+

doc/upgrading-liquibase.md

@@ -0,0 +1,22 @@
+Upgrading the version of Liquibase itself
+-----------------------------------------
+
+Most of the time, new versions of Liquibase work the same as old ones, but sometimes a new version
+will have compatibility issues with existing change sets, as happened when Liquibase released
+version 3.  When this happens, we recommend the following procedure to do the upgrade:
+
+1. Make sure all of your Liquibase managed databases are up-to-date by running `gradle update` on
+   them *before upgrading to the new version of the Liquibase plugin*.
+
+2. Create a new, throw away database to test your Liquibase change sets.  Run `gradle update` on the
+   new database using the latest version of the Liquibase plugin.  This is important because of the
+   deprecated items in the Groovy DSL, and because there are some subtle differences in the ways the
+   different Liquibase versions generate SQL.  For example, adding a default value to a boolean
+   column in MySql using `defaultValue: "0"` worked fine in Liquibase 2, but in Liquibase 3, it
+   generates SQL that doesn't work for MySql - `defaultValueNumeric: 0` needs to be used instead.
+
+3. Once you are sure all of your change sets work with the latest Liquibase plugin, clear all
+   checksums that were calculated by the old version of Liquibase 2 by running
+   `gradle clearChecksums` against all databases.
+
+4. Finally, run `gradle changelogSync` on all databases to calculate new checksums.