Appendix A. Reference material

A.1. About rule story points

A.1.1. What are story points?

Story points are an abstract metric commonly used in Agile software development to estimate the level of effort needed to implement a feature or change.

The Migration Toolkit for Applications uses story points to express the level of effort needed to migrate particular application constructs, and the application as a whole. It does not necessarily translate to man-hours, but the value should be consistent across tasks.

A.1.2. How story points are estimated in rules

Estimating the level of effort for the story points for a rule can be tricky. The following are the general guidelines MTA uses when estimating the level of effort required for a rule.

Level of EffortStory PointsDescription

Information

0

An informational warning with very low or no priority for migration.

Trivial

1

The migration is a trivial change or a simple library swap with no or minimal API changes.

Complex

3

The changes required for the migration task are complex, but have a documented solution.

Redesign

5

The migration task requires a redesign or a complete library change, with significant API changes.

Rearchitecture

7

The migration requires a complete rearchitecture of the component or subsystem.

Unknown

13

The migration solution is not known and may need a complete rewrite.

A.1.3. Task category

In addition to the level of effort, you can categorize migration tasks to indicate the severity of the task. The following categories are used to group issues to help prioritize the migration effort.

Mandatory
The task must be completed for a successful migration. If the changes are not made, the resulting application will not build or run successfully. Examples include replacement of proprietary APIs that are not supported in the target platform.
Optional
If the migration task is not completed, the application should work, but the results may not be optimal. If the change is not made at the time of migration, it is recommended to put it on the schedule soon after your migration is completed. An example of this would be the upgrade of EJB 2.x code to EJB 3.
Potential
The task should be examined during the migration process, but there is not enough detailed information to determine if the task is mandatory for the migration to succeed. An example of this would be migrating a third-party proprietary type where there is no directly compatible type.
Information
The task is included to inform you of the existence of certain files. These may need to be examined or modified as part of the modernization effort, but changes are typically not required. An example of this would be the presence of a logging dependency or a Maven pom.xml.

For more information on categorizing tasks, see Using Custom Rule Categories.

A.2. Additional resources

A.2.1. Reviewing existing MTA XML rules

MTA XML-based rules are located on GitHub at the following location: https://github.com/windup/windup-rulesets/tree/master/rules-reviewed.

You can fork and clone the MTA XML rules on your local machine.

Rules are grouped by target platform and function. When you create a new rule, it is helpful to find a rule that is similar to the one you need and use it as a starting template.

New rules are continually added, so it is a good idea to check back frequently to review the updates.

A.2.1.1. Forking and cloning the Migration Toolkit for Applications XML rules

The Migration Toolkit for Applications windup-rulesets repository provides provide working examples of how to create custom Java-based rule add-ons and XML rules. You can use them as a starting point for creating your own custom rules.

You must have the git client installed on your machine.

  1. Click the Fork link on the Migration Toolkit for Applications Rulesets GitHub page to create the project in your own Git. The forked GitHub repository URL created by the fork should look like this: https://github.com/<YOUR_USER_NAME>/windup-rulesets.git.
  2. Clone your Migration Toolkit for Applications rulesets repository to your local file system:

    $ git clone https://github.com/<YOUR_USER_NAME>/windup-rulesets.git
  3. This creates and populates a windup-rulesets directory on your local file system. Navigate to the newly created directory, for example

    $ cd windup-rulesets/
  4. If you want to be able to retrieve the latest code updates, add the remote upstream repository so you can fetch any changes to the original forked repository.

    $ git remote add upstream https://github.com/windup/windup-rulesets.git
  5. Get the latest files from the upstream repository.

    $ git fetch upstream