[mapserver-commits] r13298 - trunk/docs/en/development/rfc

[svn at osgeo.org]

Author: tbonfort
Date: 2012-03-23 04:32:08 -0700 (Fri, 23 Mar 2012)
New Revision: 13298

Modified:
   trunk/docs/en/development/rfc/ms-rfc-84.txt
Log:
rfc84 body


Modified: trunk/docs/en/development/rfc/ms-rfc-84.txt
===================================================================
--- trunk/docs/en/development/rfc/ms-rfc-84.txt	2012-03-23 09:34:21 UTC (rev 13297)
+++ trunk/docs/en/development/rfc/ms-rfc-84.txt	2012-03-23 11:32:08 UTC (rev 13298)
@@ -15,18 +15,159 @@
 1. Overview
 -----------
 
-2. Benefits and Constraints
----------------------------
+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 loosing or erroneously commiting
+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.
 
-3. Ticket Tracking
-------------------
+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
+either manually on a ticket-by-ticket basis, or automatically (huge task!).
+
+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
+ - Versionned 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 developper
+  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 soem 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.
+
+- Ticket migration from the trac instance will be a time consuming task, should
+  we want to migrate them. Ticket numbering cannot be maintained, CCs will be
+  lost. I personally do not feel the need to migrate existing tickets, provided
+  the exisiting trac instance is kept up readonly for reference.
+ 
+ - migration of open trac tickets to github will represent a substantial task,
+   in the order of several days
+ - have trac send an email to the reporter of each open ticket in trac:
+
+   .. pull-quote::
+
+      You are the reporter for ticket XXXX. This trac instance is going read-only,
+      current ticket tracking is now done through http://github/url . If you think
+      that this ticket is still valid, please take the time to open a new issue on
+      github. Without reaction from your part, this trac ticket will be closed 
+      automatically in xxx months.
+
+- Administering committer access will be done through github, osgeo credentials do 
+  not apply.
+
+2. OSGEO hosting
+-----------------
+This option consists in setting up a git repository on git.osgeo.org, and migrate
+the current trac instance so that it points to this repository.
+
+Advantages
+==========
+- We keep our independance and hosting options open
+- With some work, code references in tickets (r12345 syntax) can be updated to
+  point on the correct git commit
+- No change of workflow in our usage of trac
+
+Inconveniences
+==============
+- Need to maintain and setup the trac instance with git support
+- No nifty collaboration tools provided by github
+
+
 4. Upgrade path for SVN users
 -----------------------------
 
-5. Backwards Compatibilty Issues
----------------------------------
+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 at 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
+- inform ticket reporters
+
 6. Bug ID
 ---------