VTK/Patch Procedure

From KitwarePublic
Jump to: navigation, search

NOTE: The content on this page has been replaced by: http://www.vtk.org/Wiki/VTK/Git/Develop

VTK "Patches"

Note - this page is not updated - kitware switched to git from cvs and didn't get to update this page yet.

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 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 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. If the merge master has any questions regarding your changes, he may ask you to clarify something or change something. He may even refuse your request if there is a reason for that. The process may take some time, even sometimes as long as a few weeks, before the merge is actually done, but it will be done, or refused with an explanation. After it's over, the merge master will typically reply to your email letting you know the final result of your request.

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.