[Paraview-developers] Proposed changes to ParaView Git Workflow

[Utkarsh Ayachit]

Folks,

We are getting close to transitioning to the new git-workflow (thanks
to Brad King for painstakingly identifying possible issues we may run
into and developing infrastructure to avoid/recover from them). Brad
has written a simplified set of instructions for developers
http://public.kitware.com/Wiki/ParaView/Git/Develop. Now would be a
good time for ParaView developers to start skimming over these. If all
goes well, we should be able to transition to the new workflow as
early as next week.

Utkarsh



On Fri, Apr 15, 2011 at 2:18 PM, Utkarsh Ayachit
<utkarsh.ayachit at kitware.com> wrote:
> Folks,
>
> It has been almost an year since ParaView and VTK migrated to git from
> CVS as the version control system. Now that everyone has become
> accustomed to using git, it's time to unleash some of its capabilities
> to streamline the maintenance, development and release process. This
> email summarizes the changes planned. Please feel free to voice any
> concerns or feedback that you may have.
>
> This proposal also changes the ParaView release cycle and versioning
> conventions.
>
> Currently ParaView uses two branches "master" and "release". "master"
> is pretty much analogous to the CVS head. Developers made topic
> branches from "master" and merged them back to "master" when they
> were ready to commit (possibly using the stage). No dashboards would
> test your branch until it was merged into "master". This meant that
> time and again the master would be "unstable". This meant that come
> time to release, we have to spend extra man-hours cleaning up
> dashboards. This proposal ensures that the "master" can be maintained
> at a "stable" condition without inhibiting rapid development.
>
> The gory details will be covered in a separate Wiki page. The major
> bullets can be summarized as follows:
>
> Commits to ParaView
> -----------------------------------
> * ParaView repository will have 3 branches:
>  -> release
>  -> master
>  -> next
> * Developers start topic branches from "master" (or "release") and do
> their development.
> * Once they are ready to merge or ready to test the code on
> dashboards, they merge the topic branch to "next" using stage.
> * The ParaView continuous and nightly dashboards will test the "next"
> branch. Consequently every developer can get the testing results for
> his code. He can add more commits to his topic branch to address any
> issues that the dashboards exposed and merge those into next as well.
> * Once every week, members of the core ParaView development team will
> meet to identify topic branches in next that are "stable" and ready to
> be merged to "master". This may involve communicating with the topic
> developer for clarifications etc.
> * No topic branch will be accepted for a merge to "master" unless all
> dashboard issues are addressed. This will ensure that "master" remains
> stable. One must note that developers always start their topic branches off
> master, hence they will always have a solid starting point.
> * Every time we cut a release, we can simply tag a commit on the
> master and fast-forward the release branch to that location. Minor
> patches can go into this branch for patch releases if needed.
> * Note that no topic branch should ever start from "next" or merge anything from
> "next".
>
> Commits to VTK Submodule
> ------------------------------------------
> To isolate ParaView from constant changes to VTK, ParaView will use
> its own clone of VTK. This will be a nearly exact duplicate of the official VTK
> repository posted at a separate URL with some additional ParaView specific
> branches. The master in this clone will automatically track
> the official VTK-master. It will be a read-only mirror of the upstream i.e. the
> official VTK repository. This clone will have two new integration branches,
> pv-master and pv-next. ParaView's "master" can refer to commits in
> pv-master alone while "next" can refer to commits in "pv-next" alone. Also
> pv-master will always be merged into pv-next.
>
> In general pv-next can be considered a *less* stable staging ground for changes
> ParaView developers want to make to VTK when compared with VTK's master, while
> pv-master can be considered *more* stable than VTK-master because it will
> contain only the subset of topics that have been tested in ParaView.
> Of course, there are plans to
> clean up VTK's workflow in near future too. That will ensure a more stable
> VTK-master, in which case the pv-master will be fast-forwarded to the VTK-master
> on a more regular basis, but that's immaterial for this discussion.
>
> pv-master will always be merged into VTK master too ensuring that the two don't
> diverge. Thus it will be the ParaView developer's responsibility to get his
> code approved for VTK (possibly using gerrit). Server-side checks will ensure
> that you cannot bring in a topic into pv-master unless it's merged succesfully
> into VTK's master. This ensures that pv-master doesn't end up becoming a branch
> off VTK with 'hacks' for ParaView.
>
> Periodically, whenever VTK's master is deemed stable e.g. just before a release,
> it will be merged into pv-master. Thus bringing in any validated new changes and
> enchancements from VTK into ParaView.
>
> Versioning
> -------------------------------------------
> To help identify the development versions and released versions, our
> convention has been using odd minor numbers for development e.g. 3.9,
> 3.11, while even numbers for releases eg. 3.8, 3.10. This is no longer
> necessary. Instead the version of any development will be
> <latest-stable-release>-<CommitCount>-<Commitid>, where CommitCount is the
> number of commit since the lastest-stable-release tag and Commitid is a reduced
> SHA for the commit. (Look at the documentation for 'git describe' for additional
> details). Thus we can abandon the
> odd-even convention and have stable releases numbered 3.12, 3.13 etc. Note that
> this versioning scheme will be expressive enough that when reporting bugs, if
> one simply specifies the version number even when using any arbitrary
> development binary, we can tell exactly what source version it was built from.
>
> Release Cycle
> ---------------------
> Currently we have a major release e.g. 3.8, 3.10 every 6 months, while
> a patch release 3.8.2, 3.8.3 etc every 3 months. Instead, we can do a
> full featured release every 3 months. This is possible because we can
> maintain the master relative stable. This would also avoid the burden
> of back-porting commits over to the release branch for the 3-month
> release. Of course, we can always cut patch releases if any critical
> defects are detected following a release.
>
> Utkarsh
>