[Paraview-developers] Proposed changes to ParaView Git Workflow

[Utkarsh Ayachit]

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