VTK/Patch Procedure

VTK "Patches"

To submit a "patch" for inclusion in a VTK release branch please follow the directions on this page.
VTK-5-4 is the current release branch.

Only those changes that follow the guidelines on this page will be accepted.
Only those changes that have been screened by a nightly dashboard cycle on CVS HEAD will be accepted.
   Yes, you have to wait until tomorrow.
   No, you may not have an exception.

Zack Galbreath at Kitware, Inc. is the current VTK merge master.

The VTK merge master has some scripts that make the process of merging from CVS HEAD to a release branch as painless as possible.

One of the scripts takes as its input a simple text file that looks something like this:

 Rendering/Testing/Cxx/TestGaussianBlurPass.cxx new revision: 1.2; previous revision: 1.1
 Rendering/Testing/Cxx/TestGenericVertexAttributesGLSLAlphaBlending.cxx new revision: 1.3; previous revision: 1.2
 Rendering/Testing/Cxx/TestGenericVertexAttributesGLSLDepthPeelingPass.cxx new revision: 1.4; previous revision: 1.3
 Rendering/Testing/Cxx/TestTranslucentLUTDepthPeelingPass.cxx new revision: 1.2; previous revision: 1.1

Commit & Save, Verify Green, ... (lather, rinse, repeat...)

When making a commit to VTK CVS HEAD that you will also want merged to a branch, please save the following information:

• the cvs command you used to commit, including your commit log message:

 cvs commit -m "BUG: Fix issue #8417. vtkAxisActor tick placement was incorrect at the end of the interval. Use <= instead of < to get correct tick placement."

• the output of the cvs command:

 /cvsroot/VTK/VTK/Hybrid/vtkAxisActor.cxx,v <-- vtkAxisActor.cxx
 new revision: 1.7; previous revision: 1.6

• any further explanation you feel might be necessary to convince the merge master that your change is worthy of merging to the release branch:

 Zack, this is really a simple fix that several people have asked for on the mailing list. We really ought to merge it to VTK-5-4.

All of this information is critical for making corresponding merges on the release branch. Without this information, your "patch" will not be merged to the release branch. With this information, it's easy to construct a text file like the example shown above... and that facilitates making the merge as close to automated as possible.

Now, once you have all this information...

:WAIT_OVERNIGHT

• Wait overnight until the dashboard results are in

• If there are any problems on the dashboard, { make changes to fix them; commit them; save more cvs commands and output; goto :WAIT_OVERNIGHT; // again! }

• If you are here, then the dashboard is clean with respect to your changes...

Finally, you are ready to request the merge:

• Send email to Zack Galbreath with "VTK-5-4 Merge Request" as the subject and your saved cvs commands and output as the body

   Zack's email address is "zack d-o-t galbreath _at_ kitware d-o-t com"

The VTK merge master is often a busy creature. Your request will not go unnoticed, though. It may take some time, even sometimes as long as a few weeks, before the merge is actually done, but it will be done. After it is done, the merge master will typically reply to your email letting you know your changes are in the release branch, too.

The VTK anti-Patch

Here's what *NOT* to do:

• Do NOT assume that you can skip the waiting overnight part
• Do NOT send a *.patch file against the existing branch
• Do NOT send cvs diffs against CVS HEAD or the release branch

Here's why:

Sending the output of cvs tells the merge master the exact revisions in CVS HEAD that should be merged to the release branch. Using that information, the merge master can easily determine exactly when the commit was made, and he (or she) can inspect the appropriate days on the dashboard to verify that he agrees that the commit "passes inspection."

If you send a patch, or a diff against CVS, or you don't wait overnight, then you have not proven that your patch is worthy of being merged to a release branch. Strive for green always grasshopper. Strive for green. Follow this process and learn patience, o VTK developer.