.. _rfc84:

=========================================================================
MS RFC 84: Migrate project repository from svn to git
=========================================================================

:Date:  2012-03-23
:Author: Thomas Bonfort
:Contact: tbonfort at terriscope dot fr
:Status: Adopted
:Version: MapServer 6.2

1. Overview
-----------

While SVN suits our needs as a collaborative source code versionner, it
has  shortcomings that make it difficult to work with for
developpers working on multiple tasks in parallel. Git's easy branching
makes it possible to set up branches for individual task, isolating
code changes from other branches, thus making the switch from one task
to another possible without the risk of losing or erroneously committing
work-in-progress code. Three-way merging of different branches means that
merging code from one branch to another becomes a rapid task, by only having
to deal with actual conflicts in the code. Offline committing and access
to entire history make working offline possible.

There is already somewhat of a consensus that the migration from SVN to git is
a good move. Discussion remains as to how this transition should be performed.
This RFC outlines the different options available for hosting the official
repository, and the different options available for our ticket tracking.

Current investigation has retained two majors options that we could go down
with:

- Repository migrated to github, use github provided issue tracking. This
  option will be referred to as  "Github hosting".
- Repository hosted by osgeo, current trac instance migrated to hook
  on the new repository. This option will be referred to as "Osgeo hosting"

2. Github hosting
-----------------
This option consists in moving our entire code+ticket infrastructure
to github. The current trac instance becomes nearly read-only, new 
tickets cannot be created on it. Existing tickets are migrated to github
with a script taking a trac postgresql dump (once the migration starts,
our trac instance becomes read-only).

Advantages
==========
- Code hosting:
 
 - No need to worry about hosting infrastructure
 - Can be up and running in a short delay
 - Support for pull requests, allowing external contributions to be rapidly
   merged into our repository
 - Online code editing for quick fixups
 - Github visualization tools, for example to check which branches are likely
   to contain conflicting code sections
 - Code and patch commenting make collaboratively working on a given feature
   very lightweight, i.e. just at your comment on the code line which seems 
   problematic to you
 - Documentation contributions highly simplified for one-shot contributions.

- Issue tracking:

 - Integration of ticket state with commit messages (e.g: "fix mem allocation
   in mapDraw(), closes issue #1234
 - Email replies to ticket notifications
 - The free-form label tagging of issues might open up some interesting usages
 - Versioned text-base attachments (gists), with commenting


Inconveniences
==============
- Hosting by a private company, which might become an issue if their TOS evolve
  or if they go out of business. The source code availability is not an issue
  as is possible to maintain a mirror on an osgeo server, and each developer
  has a checkout of the full source control history. Ticket migration would be
  an issue, but there are APIs available to extract existing tickets.
- Issue tracker is in some ways less featurefull than trac. The only hardcoded
  attributes are the assignee and the milestone. All the other triaging
  information goes into free formed labels, a la gmail.
 
 - No way to automatically assign a ticket owner given a component
 - No support for image attachments, can be referenced by url but must be
   hosted elsewhere.
 - No support for private security tickets

- Administering committer access will be done through github, osgeo credentials do 
  not apply. Git does not support fine-grained commit permissions per directory, there
  will be a separate repository for the docs to account for the larger number of
  committers there.

3. Git Worflows
---------------

Stable Branches
===============

This document outlines a workflow for fixing bugs in our stable branches:
http://www.net-snmp.org/wiki/index.php/Git_Workflow
I believe it is a very good match for our stable release management:
- pick the oldest branch where the fix should be applied
- commit the fix to this oldest branch
- merge the old branch down to all the more recent ones, including master

Release Management
==================

Instead of freezing development during our beta cycle, a new release branch is
created once the feature freeze is decided, and our betas, release and
subsequent bugfix releases are tagged off of this branch. Bug fixes are
committed to this new stable branch, and merged into master. New features can
continue to be added to master during all the beta phase.
http://nvie.com/posts/a-successful-git-branching-model/ is an interesting read 
even if it does not fit our stable release branches exactly.


4. Upgrade path for SVN users
-----------------------------

For those users who do not wish to change their workflow and continue with SVN
commands. This is not the recommended way to work with git, as local or remote 
changes might end up in having conflicts to resolve, like with svn.

checkout:
 - git clone git@github.com:mapserver/mapserver

update
 - git pull origin master

commit files
 - git add [list of files]
 - git commit -m "foo"
 - git push origin master

fix in branch, and merge fix into master
 - git checkout ms-branch-6-0
 - git add [list of files]
 - git commit -m "foo"
 - git push origin ms-branch-6-0
 - git checkout master
 - git merge ms-branch-6-0
 - git push origin master

5. Tasks
--------
- import svn to git
- assign github users
- split into sub-projects (c.f. rfc83):
  
  - mapserver
  - mapcache
  - tinyows
  - msautotest
  - docs

- document release process
- migrate website scripts
- switch trac site to read-only

6. Bug ID
---------

* TBD

6. Voting history
-----------------

+1 from ThomasB ,MikeS, UmbertoN, HowardB, SteveW, DanielM, SteveL,
TamasS, JeffM, AssefaY, TomK, PerryN

-0 from OlivierC
