Upload Gists automatically with Maven

Snippets of code rarely works. When they do, it’s difficult to maintain them and keep them in pace with the new versions of the software where they are extracted.

With the purpose of having tested and automatically uploaded snippets of code, I have created the plugin: vromero.github.io/gist-maven-plugin/

With this plugin it is possible to demarcate portions of an XML, Java or JSP files:

public class Java {

    // START SNIPPET: snip-id
    public static void main( String[] args ) {
        System.out.println( "Hello World!" );
    }
    // END SNIPPET: snip-id
}

This demarcations will be sent to GitHub’s Gist to create or update previous snippets.

Gist

Snippets could be backed by tests, effectively rendering them exact and maintainable if any the the dependencies shift versions over the time.

Demarcation

The gist-maven-plugin follows intentionally the same snippet demarcation convention than Doxia. The reason behind this is to be able to use the same snippet demarcators to generate maven documentation and gists, e.g:

Java

    // START SNIPPET: snip-id
    public static void main( String[] args ) {
        System.out.println( "Hello World!" );
    }
    // END SNIPPET: snip-id

XML

<!-- START SNIPPET: snip-id -->
<navigation-rule>
    <from-view-id>/logon.jsp</from-view-id>
    <navigation-case>
          <from-outcome>success</from-outcome>
          <to-view-id>/mainMenu.jsp</to-view-id>
    </navigation-case>
</navigation-rule>
<!-- END SNIPPET: snip-id -->

JSP

<%-- START SNIPPET: snip-id --%>
<ul>
    <li><a href="newPerson!input.action">Create</a> a new person</li>
    <li><a href="listPeople.action">List</a> all people</li>
</ul>
<%-- END SNIPPET: snip-id --%>

Plugin Configuration

This plugin is published to the Sonatype OSS Repository and therefor, is available from maven central. No special repository configuration is required.

<plugin>
    <groupId>org.vromero</groupId>
    <artifactId>gist-maven-plugin</artifactId>
    <version>1.0.0</version>
    <configuration>
        <username>MyUserName</username>
        <password>myp4ssw0rd!</password>
        <outputDir>${project.build.directory}/gists</outputDir>
        <gists>
            <gist>
                <correlationStrategy>DESCRIPTION</correlationStrategy>
                <description>${mule.documentation.version}_message-sources_flowWithPoll</description>
                <public>true</public>
                <files>
                    <file>
                        <location>src/main/app/message-sources.xml</location>
                        <snippetId>flowWithPoll</snippetId>
                        <gistFileName>${mule.documentation.version}_message-sources_flowWithPoll</gistFileName>
                    </file>
                </files>
            </gist>
        </gists>
    </configuration>
</plugin>
  • plugin/configuration/outputDir is optional, with a default value of: ${project.build.directory}/gists.
  • plugin/configuration/gist can be repeated a number of times.
  • plugin/configuration/gist/files/file can be repeated a number of times.
  • plugin/configuration/gist/correlationStrategy is mandatory and the only acceptable values are DESCRIPTION and NONE at the moment. This represents how this plugin will correlate the local snippet with the gist’s snippet. Given that there is not externalId attribute on gist, description is the only mechanism possible. A feature request has been raised to gist, when this become available correlationStrategy will be optional and will take the externalId correlation as default value. Meanwhile, this will remain mandatory.
  • plugin/configuration/gist/files/file/gistFileName represents the name the snippet will have in gist.

Plugin Execution

mvn org.vromero:gist-maven-plugin:snippet
mvn org.vromero:gist-maven-plugin:deploy

This can be simplified by adding the following pluginGroup to the pluginGroups section of your $HOME/.m2/settings.xml .

<pluginGroups>
    <pluginGroup>org.vromero</pluginGroup>
</pluginGroups>

With this pluginGroup added we can invoke the mojos with:

mvn gist:snippet
mvn gist:deploy