Contributing

To contribute an extension to the Liquibase community, you simply have to create a new page under Available Extensions containing the compiled .jar file as well as instructions for usage. You may also want to announce it on the Liquibase forum. For examples and starting points, see Set Identity Insert and Vacuum.

Contact Information

Please remember to include contact information with your extension documentation.

Packaging

Plug-ins generally integrate best as a .jar file.  To keep consistant naming, use the form liquibase-PLUGIN-NAME-VERSION.jar.  This form will help end-users recognize Liquibase plugins within their jar directories as well as know the version number at a glance.

Within your jar, you can use any package name you like.  There are several packages that are automatically scanned by Liquibase for extensions:

  • liquibase.ext
  • liquibase.change.ext
  • liquibase.sqlgenerator.ext
  • liquibase.database.ext
  • liquibase.parser.ext
  • liquibase.precondition.ext
  • liquibase.serializer.ext

If you create your classes in those packages, or subpackages (recommended), they will automatically be found.  If you store your classes in a different package, include the package name under the Liquibase-Package attribute in your META-INF file.

Source Control

While we do not require extensions to be open source, if it is please include a link to your source control system or a way to download a source distribution.  It will help users out and will help you out if/when patches are submitted.

The easiest and most flexible approach is to create a project on github.com for your extension for both git hosting and issue tracking. 

Issue Tracker

If you have a publicly available issue tracker, please link to it. The Liquibase extension portal has a Jira-based issue tracker available if you would like to use it. Contact nathan at voxland.net to be given access.

Labeling your Extension

You can specify "labels" tagging your page/extension here in the extension portal. Please add them to help categorize and sort extensions in the future.

XSD Schemas

Since Liquibase primarily uses an XML-based format for changelog files, you may want to include an XML schema on your page. If you create your own namespace, you can use the form http://www.liquibase.org/xml/ns/dbchangelog-ext/YOUR-EXTENSION, or whatever you choose. If you do not create a custom schema, end-users should use http://www.liquibase.org/xml/ns/dbchangelog-ext.

Recommended Documentation

Think of the questions end-users will have using your system, and be sure to answer them. Valuable information that may be applicable to your project includes:

  • Supported Databases
  • Dependencies required for building and using the extension
  • Liquibase version(s) tested against
  • Exposed changelog tags/commands and their attributes and/or sub-tags
  • Code samples