.. _git:

*****************************************************************************
 GitHub
*****************************************************************************

Background
==========

Since April 2012, MapServer's source code and documentation are under GitHub control
(https://github.com/mapserver).  In the past, MapServer has also used
Subversion and CVS for version control.

GitHub Sub-Projects
===================

Several sub-projects are used on GitHub, to separate files for the MapServer
source, or documentation, for example.  Here are a list of the important
sub-projects:

1. `/mapserver <https://github.com/mapserver/mapserver/>`__: MapServer source

2. `/docs <https://github.com/mapserver/docs/>`__: Documentation files, stored 
   as restructured text files.

3. `/mapcache <https://github.com/mapserver/mapcache/>`__: MapCache source, used 
   for tile caching.

4. `/msautotest <https://github.com/mapserver/msautotest/>`__: msautotest files,
   used for automatically verifying source changes.
   
5. `/basemaps <https://github.com/mapserver/basemaps/>`__: basemaps files,
   used to generate mapfiles from OpenStreetMap data.
   
6. `/ms-ogc-workshop <https://github.com/mapserver/ms-ogc-workshop/>`__: OGC Workshop files,
   an excellent resource for learning OGC standards (WMS/WFS/WCS/SOS) with MapServer.

Code Developer's GitHub Access
==============================

Github access is mostly intended for use by developers, but users can also
access the MapServer source between releases as it is being developed. Github
access is only recommended for those who need the absolute latest and greatest
code, if they are not afraid of getting their hands dirty building the source.
The Github repository does not contain `GD <http://www.boutell.com/gd/>`__ or
any of the support libraries, and it requires flex and bison to build it.
Building MapScript will also require `SWIG <http://www.swig.org>`__ be
installed on your machine. Here's how to access the source:

1. Create a `free personal account <https://github.com/plans/>`__ at GitHub

2. See GitHub's `help guidelines <https://help.github.com/articles/set-up-git/>`__ to 
   install Git locally

3. Issue `git clone git@github.com:mapserver/mapserver.git` to
   check out a copy of the current source/master into your working directory.

Support Libraries
=================

Information about supporting libraries and how to compile MapServer from
source can be found in the :ref:`unix` or :ref:`win32`.

How to Obtain Commit/Push Access
================================

If you find yourself submitting a lot of push requests to GitHub, or you would 
like to be an active developer that picks up the maintenance of a portion of MapServer, 
contact Steve Lime, one of the other developers, or send a message to the MapServer-dev :ref:`lists`.
To obtain GitHub commit/push access, an individual must:

- demonstrate expertise about a specific area 
- be willing to put more time into the project than just the short term
  (dumping code into the project and providing no way to maintain it is almost
  as bad as having no code at all)
- be active instead of casual about the project.
- election of Subversion committers is covered in :ref:`RFC 7.2: MapServer Commit Management <rfc7.2>`

Issue Trackers
==============

- the main Issue Tracker for the MapServer source is found at: https://github.com/mapserver/mapserver/issues
- the Issue Tracker for documentation is found within the docs sub-project at: https://github.com/mapserver/docs/issues
