Description

WSIT Build Tools provides a set of Ant tasks and Maven mojos that generate WSIT configuration files for Metro web services.

Download

Prior published versions are available from the central repository: http://repo1.maven.org/maven2/com/codeplex/wsitbt/

The project homepage is: http://wsitbt.codeplex.com

Usage

See Getting Started for instructions on how to use these tools.

Codeplex does not support directly publishing web content, so the maven generated web site is published here: Maven Generated Site

There is also obsolete wiki documentation on codeplex: http://wsitbt.codeplex.com/documentation.

Docs on docs

The web page you are reading now is generated from the file: ./src/site/apt/index.apt.vm. Edit that file to add new documentation using the "Almost Plain Text" (APT) format.

  • To locally generate this documentation, run:
    mvn site

    You can view the locally generated site by opening target/site/index.html in a browser.

  • To locally generate a fully linked site (including sub-modules), run:
    mvn site site:stage

    You can view the complete locally generated site by opening target/staging/index.html in a browser.

For documentation on how to write documentation (like the documentation you see here), see the following documentation: (I dare you to say that 10 times, real fast.)

RTFM to WTFM.

Release Steps

Follow the steps below to do an official release of the project.

  • License Headers - Some validation logic (for example the maven-license-plugin) is only executed during the release process. In order to avoid validation failures during the release build, you may want to manually run these checks via:
    mvn license:check

    If some license headers are missing from files, you can use the command below to add the missing license headers:

    mvn license:format
  • GPG - The maven-gpg-plugin is used to sign released artifacts during the "verify" phase. This plugin requires some one-time setup (a native GnuPG program and your gpg key):

    From GPG Usage:

    • You need to have previously configured the default key.
    • gpg also needs to be on the search path.

    To make sure you have gpg configured correctly, you can manually run the "verify" phase and mimic the release environment via:

    mvn verify -DperformRelease=true -DskipTests
  • Server Settings - a number of additional server tags need to be configured to do a release. You should add these to your .m2/settings.xml file (with your own valid user/password values of course):
        ...
        <servers>
        ...
           <!-- sonatype open source repos for sync to maven central -->
           <server>
               <id>sonatype-nexus-snapshots</id>
               <username>mySonatypeUser</username>
               <password>mySonatypePassword</password>
           </server>
           <server>
               <id>sonatype-nexus-staging</id>
               <username>mySonatypeUser</username>
               <password>mySonatypePassword</password>
           </server>
    
           <!-- sourceforge login - used to publish generated maven docs -->
           <server>
               <id>wsitbt-site-generated</id>
               <username>mySourceForgeUser</username>
               <password>mySourceForgePassword</password>
           </server>
    
           <!-- codeplex login - to write to source code bank -->
           <server>
               <id>hg01.codeplex.com</id>
               <username>myCodeplexUser</username>
               <password>myCodeplexPassword</password>
           </server>
           ...
        <servers>
        ...

    NOTE: The perform operation described below will attempt to execute the site:deploy goal. Be sure you open and connect a SourceForge command shell before you execute the perform operation.

    ssh -t <mySourceForgeUser>,wsitbt@shell.sf.net create

    This allows you to publish the generated site via the validated sourceforge shell. For more info, see: Deploying to sourceforge.net.

  • Bundle docs - The 'bundle' project includes the 'staged' site docs, so be sure you have executed 'site:stage' before you do the release to ensure the './target/staging' directory exists and will be included in the bundle .zip file.

    @todo NOTE: This is not working as intended. Look into other options to include staged site in the bundle .zip file.

    mvn package site site:stage
  • Prepare the release (see: Prepare a Release)
    mvn release:prepare

    If any problems occur, you can immediately rollback changes or clean changes.

    mvn release:rollback
    or
    mvn release:clean
  • Perform the release (see: Perform a Release)
    mvn release:perform

    If any problems occur, you can immediately rollback changes via:

    mvn release:rollback

    NOTE: The prepare and/or perform process may create "tags" in the mercurial bank. Currently the "clean" and "rollback" operations do not appear to remove these tags, so you must manually remove such a tag before re-trying the release. You can remove the tag via:

    hg tag --remove <tag name>
    hg push
  • Post Release Steps - After the maven 'release' if finished, you still need to do a few housekeeping tasks:
    • 'Promote' the release - Follow the steps in Sonatype OSS Maven Repository Usage Guide, particularly from step 8. Release It.

      You need to login to the Sonatype Staging Repository and close, then release the newly published artifacts in the Sonatype Staging Repository.

    • Create new Codeplex Release - Create a new 'Release' under the 'Downloads' tab on the codeplex site: http://wsitbt.codeplex.com.

      Set the new bundle zip file as the download file. For example, download http://repo1.maven.org/maven2/com/codeplex/wsitbt/bundle/1.0.7/bundle-1.0.7.zip from the maven central repository, and make that file the download file for the new release.

      If the central repo is not yet synchronized with the Sonatype repo, you could download the bundle file from the Sonatype Releases Repository.

      In the 'Release Details' section, set 'Development Status' to: 'Beta', 'Show to public?': Yes, 'Recommended release?': Yes, 'Replace recommended release?': Yes.

      In the 'Release Details' section, add the 'Change set number' from the label created in hg when you ran 'mvn release'. You can find the 'Change set number' by looking under the 'Source' tab on codeplex, and look for the a row with a comment like:

      wsit-build-tools-project-1.0.3 [maven-release-plugin] prepare release wsit-build-tools-project-1.0.3

      Copy the 'Change set' value of that row and paste it into the 'Change set number' field in the 'Release Details' section.