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 Runtimes 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 MTR uses when estimating the level of effort required for a rule.
| Level of Effort | Story Points | Description |
|---|---|---|
| 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 MTR XML rules
MTR XML-based rules are located on GitHub at the following location: https://github.com/windup/windup-rulesets/tree/master/rules/rules-reviewed.
You can fork and clone the MTR 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 Runtimes XML rules
The Migration Toolkit for Runtimes 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.
-
Click the
Forklink on the Migration Toolkit for Runtimes 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. Clone your Migration Toolkit for Runtimes rulesets repository to your local file system:
$ git clone https://github.com/<YOUR_USER_NAME>/windup-rulesets.git
This creates and populates a
windup-rulesetsdirectory on your local file system. Navigate to the newly created directory, for example$ cd windup-rulesets/
If you want to be able to retrieve the latest code updates, add the remote
upstreamrepository so you can fetch any changes to the original forked repository.$ git remote add upstream https://github.com/windup/windup-rulesets.git
Get the latest files from the
upstreamrepository.$ git fetch upstream
A.2.2. Additional resources
- MTR Javadoc: http://windup.github.io/windup/docs/latest/javadoc
- MTR Jira issue tracker: https://issues.redhat.com/projects/WINDUP
- MTR mailing list: windup-eng@redhat.com
Revised on 2023-03-16 15:54:34 UTC
