[Paraview] Proposed changes to ParaView Git Workflow

[Utkarsh Ayachit]

Folks,

If you were delaying reading the wiki pages until the transition to
the new git workflow, it's now that time :). The transition has
happened. The continuous dashboard will be updated to track "next"
soon. The ParaView/Utilities/SetupForDevelopment.sh has been updated
to include new alias and remotes for PVVTK as well, so you may want to
re-run that script.

Updated set of instructions are available at (thanks to Brad King):

http://paraview.org/Wiki/ParaView/Git

Happy git-ing!

Utkarsh

On Wed, Jun 15, 2011 at 5:01 PM, Utkarsh Ayachit
<utkarsh.ayachit at kitware.com> wrote:
> 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
>>
>