PMML Change Management Process

Introduction

This is a description of the change management process adapted by the DMG. It is built around the JIRA Bug Tracker in which you can repoert the issue by adding information on the button below and the GIT Repository (browse-able here). The Git Repository is available on SourceForge PMML Project while JIRA is managed by the DMG.

The key goals of the process are:

• Use tools and technology to make our jobs easier and our output more reliable and consistent.
• Make real and effective use of version control. This includes maintaining working proposals and, more importantly, merge approved proposals on a continuous basis.
• Have the ability to easily and clearly see differences between versions, without requiring manual special marking of changes (e.g. use red fonts). It includes the ability to see small incremental changes on a working proposal or full differences to the base (published) version.
• Use the (better) bug tracking system regularly, both as the main "agenda-driver" for our calls and the place to record decisions.
• Have the ability to easily and quickly track and review progress towards a release.
• Ensure painless and reliable releases as soon as all scheduled proposals are approved

PreHTML

The PMML working group maintains versions of the PMML as .prehtml which is an .xml file. Using .prehtml allows members to quickly and easily make sure that any proposed changes to the standard do not conflict with the existing standard. It relies on a Python 2.7 file, found in Sourceforge as /bin/makeHTML.py that reviews all .prehtml, and if no conflicts exist, generates the xsd and html to be added to the DMG site.

The makeHTML script validates all examples given and checks for any conflicts. If an example is included and the tag "prehtml:example quoted="true"" is used, please note that it is important to use html alternatives for internal brackets like "&alt;" instead of "<".

Source Control

We are using GIT for maintaining released versions of PMML, along with branches for approved resolutions and working proposals. For more information about GIT, see using-git.html. As of PMMLv4.3, we maintain two kinds of branches:

Master Branch

A single master branch (named master) where the release manager prepares the upcoming version.

Approved Branches

A separate branch is created and maintained for each released version. This is where all approved proposals for that particular version are merged. Such a branch stems from the latest version of the master branch and is named with the version number followed by the suffix -approved.

In order to reap the benefits of using the source control system, different versions of each file should be easily diff-ed and compared. For this reason, it is critical that checked in prehtml files use consistent formatting. Appropriate scripts and instructions are included in the bin folder that should be used to check, correct, and reformat prehtml files as necessary.

Process

The PMML change management process is present below, broken down to five different tasks: reporting new issues, reviewing active issues, resolving issues, planning releases, and releasing new versions.

Report a New Issue

A new issue can be reported to identify a defect of the published standard, request an enhancement, or propose new feature. Go to the report issue button above to Report Issue page and enter all relevant information. Please make sure you select a category, indicate severity, enter a descriptive enough (but short) summary, and provide a full description. If necessary, you may use the additional information field to add extensive details. You may also upload files related to the issue.

Issue Review

Issues are being reviewed by DMG on the bi-weekly regular call. The review has three goals:

1. Review and vote on any GROUPREVIEW issues.
2. Quickly assess and update issues not yet accepted (NEW, FEEDBACK, and ACKNOWLEDGED). Discussed issues may be rejected (CLOSED), accepted (CONFIRMED), or require further assessment (FEEDBACK or ACKNOWLEDGED). In some cases, critical issues may be ASSIGNED and scheduled for an forthcoming release.
3. Review and discuss proposed resolutions for active (ASSIGNED) issues. Issues remain in that status while the resolution is being worked on and until a final resolution is approved.

CONFIRMED and CLOSED issues are not considered during this review.

Release Planning

DMG holds release planning meetings (quarterly, semi-annually, and/or part of the annual face-to-face meeting) to allocate CONFIRMED issues in future version releases. Each issue tied to a particular version is ASSIGNED to DMG member. The assignee (or owner) of the issue is the lead person responsible for the resolution of the issue (see below).

When a new version is planned, the release manager creates the corresponding approved branch for the version our of the latest version of the master branch (see Source Control above)

Resolving an Issue (Proposals)

The assignee (owner) of an issue takes the lead for making and updating a proposal to resolve the issue. The owner must:

1. Create a new .prehtml document and attached to relevant issue in JIRA. NOTE: for small changes, this can sometimes be bypassed and handled by the release manager.
2. Modify files and/or create new files as necessary to reflect the proposed changes. Proposed changes should NOT be specially marked in the HTML files (no need to mark new text as red or strike through deleted text).
3. Run scripts to check, correct, and generate html from the prehtml files.
4. Email the group about your changes and update the issue in JIRA.

This process requires familiarity with GIT and the ability to run the /bin/makeHTML.py script. It also requires sufficient access privileges to the PMML GIT repository. If, for some reason, you cannot execute all the tasks yourself, you may identify someone as your "proxy committer" (e.g. the release manager).

Proposed changes checked in the source control system or JIRA are reviewed by DMG during the regular issue review calls. The GIT web browse facilities, including differences between version, can be used to review changes. If recommendations for further changes are made, the owner repeats the change steps above in preparation for the next review.

Resolution Approval

When no more changes are recommended for an issue, the resolution is ready to be voted on. The status of issue changes to RESOLVED. At the same time, it is assigned to the release manager who announces (by email) the call for vote and tracks submitted votes.

Upon approval, the working branch for the issue is merged or added to the appropriate version approved branch by the release manager. The release manager also marks the corresponding issue as CLOSED.

Version Release

When all issues associated with a particular (target) version are closed, that version is ready to be released and made publicly available as the new standard. The release manager has to perform the following tasks:

Maintaining the Website

The PMML branch of the DMG website is a collection of single .html files. As a result, when a new version is release, elements like the navigation bar on each file need to be updated. To make the site easier to maintain with each release of PMML, some python scripts have been created and stored in SF (/bin/update_vars.py and /bin/updateexistingsite.py). These scripts provide a path to programmatically create a duplicate copy of the site, incoporate html from a new release, and make all of the required updates.