Git & GitHub

The OPF strongly encourages developers to use GitHub for source code management and revision control. We'll not make the argument for revision control here, suffice to say we believe it's a good thing. We've chosen Git as a revision control tool because:

• It's widely available on all platforms.
• Developer repository clones provide de-facto backup for repositories with multiple developers.
• There's tool support for most development environments and IDEs.

We use GitHub as a central host for our repositories because:

• It's better and easier than hosting the infrastructure ourselves.
• They support Linux, Windows, and MacOS developers, and have an excellent set of help resources .
• They provide a web based API for automating development tasks.

Getting Started

GitHub have this set-up help: http://help.github.com/set-up-git-redirect e.g. for Windows: http://help.github.com/win-set-up-git/

The OPF GitHub Organisation

The OPF has a GitHub organisation page, that provides a home for its source code repositories. Anyone with a GitHub account can be made a member of the OPF organisation, if you don't have an account you can sign up here .

GitHub Teams

Access to organisation's repositories is controlled through the use of GitHub Teams, which are administered by the organisations owners. This is a changing list but always includes the OPF's admin admin(AT)openplanetsfoundation(DOT)org, other administrators include project technical leads, and OPF staff. A team can be set up for a single repository if necessary, and you'll need to be added to a team in order to commit to a repository.

GitHub Repositories

GitHub repositories are used to manage the source code for OPF software projects, they can also be used for non-code projects, e.g. XML Schema/ Ontologies, Documentation.

How Many Repositories does my Project need?

Ideally a git repository should be fairly fine grained, holding the code for a particular application or tool. The OPF's philosophy on software tools is similar to that of unix, develop small focussed tools that perform a single task well. This means that large software projects will almost certainly require multiple repositories in time. Despite the preference for fine grained tools and repositories please resist the urge to set up multiple repositories unless you really need them. A repository can be split into two or more parts at a later date, while retaining the history, so there's no reason not to start with a single repository and expand when necessary.

What can I put in a Repository?

Any of the following are welcome, the first three are mandatory, though initially documentation can be included in the README.

• a LICENSE file
• a README.md file
• good documentation (install instructions, usage examples, man files, JavaDoc, etc.)
• code (java, c, shell scripts, etc.)
• config files (xml, properties files, etc.)
• build files (poms, ant?, make)
• working unit tests (preferably with good coverage).
• small test data sets for unit tests
• good checkin comments

What shouldn't I put in a Repository?

• build artefacts (exes, wars, jars, .class files, Maven target dirs)
• containers (zips, etc.). Use the raw data and a buidl tool to create the container. Git handles compression so zips don't help.
• volatile data
• large test files
• third party artefacts (jars, apps, dlls) provide links and documents instead.

New Repository Checklist

You'll need to decide the following before requesting a repository, include the information in the request to create the repository please.

Project Information

To create a project repository for you we'll need some information about the repo, at the very least:

The information will be used to populate a minimal project information file, called .opf.yml that will be added to the project root directory. The YAML homepage provides more information, and this tutorial covers enough to get started, again the OPF administrator, or your project administrator will be able to help. The purpose of the file is to provide a minimal set of metadata about the project in a machine readable format.

The section below specifies the full set of fields available, and states which are mandatory (these fields correspond directly to the minimal project information). The specification is a well formed project specification document, items can be left out of the document as can be seen in the examples that follow the specification.

License

It pays to decide your license policy before putting your code on-line using a public code sharing service. The OPF doesn't mandate which license you should use, just that you choose one that is permissive enough to allow us to host the code. Individual projects may also choose their own license with the same stipulation, the OPF only requires that you choose and that you document the choice in a plain text LICENSE file.

Initial README.md File

When a repository is created, a README.md file will also be created in the root directory. The contents of the file are displayed on the project's Github page, this is the GitHub help page for repo creation and READNE,md. The README.md can be edited as a plain text file, but GitHub also supports GitHub flavoured Markdown for text formatting.

Initially your README should contain the following information:

• A project "mission statement", that describes:
  • What the project does, NOT a feature list, just a summary.
  • Who are the intended audience for the software.
• A contact for further information about the project.

This is the statement taken from the LibreOffice project:

Further help

• The Git book is on-line and downloadable, see http://git-scm.com/book
• For help setting up Git and GitHub, see http://help.github.com/
• See also this nice HTML5 Git cheatsheet http://www.ndpsoftware.com/git-cheatsheet.html
• Some folk find this Git cookbook useful http://www-cs-students.stanford.edu/~blynn/gitmagic/.
• If you're a Windows user GitHub provide a GUI http://windows.github.com/.
• There's a Mac GitHub client here http://mac.github.com/.
• If you use Eclipse, the eGit plugin is pretty good: http://www.eclipse.org/egit/. Here's a tutorial on how to use it: http://www.vogella.de/articles/EGit/article.html

Open Planets Foundation Development Guide by Open Planets Foundation is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.