Skip to content

Latest commit

 

History

History
85 lines (66 loc) · 3.51 KB

2.3.md

File metadata and controls

85 lines (66 loc) · 3.51 KB

2.3 How to add a configuration migration

The Go configuration XML file is a very important part of Go. When adding new features or changing existing features, sometimes there will be a need to add/remove/modify certain sections of it. Since existing configuration XMLs should continue to work, even for existing users, a "configuration migration" will need to be added to migrate old XMLs.

The configuration XML has a schema version, and configuration migration scripts correspond to that version. These scripts use XSL transformations, and below is a quick guide on how to add a new configuration migration.

Explaining by example, I'll take the case of how schema version of the configuration was migrated to 72

2.3.1 Steps to migrate configuration

Assuming the working directory to be ~/projects/go

Step 1: Backup current XSD (schema version 71)

~/projects/go$ cp ./config/config-server/resources/cruise-config.xsd ./config/config-server/resources/schemas/71_cruise-config.xsd

Step 2: Bump up version to schema version 72

  • Edit ./config/config-server/resources/cruise-config.xsd to update the attribute schemaVersion value to 72
<xsd:attribute name="schemaVersion" type="xsd:int" use="required" fixed="72"/>
  • Edit com.thoughtworks.go.util.GoConstants and set CONFIG_SCHEMA_VERSION=72
public static final int CONFIG_SCHEMA_VERSION = 72;

Step 3: Add XSL to transform the cruise-config.xml to version 72

As part of version 72, the expectation was to remove the license section from the configuration.

~/projects/go$ touch ./config/config-server/resources/upgrades/72.xsl

The 72.xsl transformation looks like

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    <xsl:template match="/cruise/@schemaVersion">
        <xsl:attribute name="schemaVersion">72</xsl:attribute>
    </xsl:template>
    <!-- Copy everything -->
    <xsl:template match="@*|node()" name="identity">
        <xsl:copy>
            <xsl:apply-templates select="@*|node()"/>
        </xsl:copy>
    </xsl:template>
    <!-- Remove matching node "<license>" -->
    <xsl:template match="//license" />
</xsl:stylesheet>

Step 4: Bump up version to schema version 72 in functional tests

The functional tests repository is at https://github.com/gocd/functional-tests

  • Update ./src/test/java/cruise-config.xsd to the latest version.
  • Edit com.thoughtworks.go.util.GoConstants and set CONFIG_SCHEMA_VERSION=72
public static final int CONFIG_SCHEMA_VERSION = 72;

2.3.2 Testing the newly added migration

Configuration migration tests can be found in com.thoughtworks.go.config.GoConfigMigrationIntegrationTest. For example, a test to verify schema version 72 is written as follows.

@Test
public void shouldRemoveLicenseSection_asPartOfMigration72() throws Exception {
    String licenseUser = "Go UAT ThoughtWorks";
    String configWithLicenseSection =
            "<cruise schemaVersion='71'>"+
                "<server artifactsdir='logs' commandRepositoryLocation='default' serverId='dev-id'>" +
                    "   <license user='licenseuser'>"+
                    "       Hq6o5X...." +
                    "   </license>" +
                "  </server>" +
            "</cruise>";

    String migratedContent = migrateXmlString(configWithLicenseSection, 71);
    assertThat(migratedContent, not(containsString("license")));
    assertThat(migratedContent, not(containsString("licenseuser")));
}