GitHub Guide

Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History

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 .

Joining the OPF GitHub Organisation
Send your GitHub user name to admin(AT)openplanetsfoundation(DOT)org in an email with a quick introduction stating:
  • your name
  • the organisation you work for
  • your reason for wanting OPF GitHub membership

Requests will be dealt with as quickly as possible, usually within 2 working days.

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.

Mandatory for all GitHub Repositories
  • Project information
    A minimal set of project information for the .opf.yml YAML metadata file.
  • License
    You should decide the license up front, and include a LICENSE file in the root project directory.
  • README.md
    You should be able to populate a minimal GitHub README.md file stating the purpose of the project, the audience, and a contact point for further information.

Project Information

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

Minimum Project Information
  • Project Name
    A short name that identifies the project and perhaps partially describes the repository.
  • Vendor
    The name of the project / organisation responsible for the repository, e.g. AQuA, SCAPE, OPF, etc. This is necessary so that it's possible for OPF staff members to easily tell who a repository belongs to, or trace ownership in lieu of a developer.
  • Project Maintainer
    The individual responsible for the project, this might be an individual developer, a development manager, or a project manager.

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.

.opf.yml Project Description File

License

State Your License
You MUST provide a plain text license statement, or a link to one with your request to create a repository. This will be used to create the project's LICENSE file.

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:

Example Mission Statement

LibreOffice is the power-packed free, libre and open source personal productivity suite for Windows, Macintosh and GNU/Linux, that gives you six feature-rich applications for all your document production and data processing needs: Writer, Calc, Impress, Draw, Math and Base. Support and documentation is free from our large, dedicated community of users, contributors and developers. You, too, can get involved!

ToDo More on README
Add a README sub-page with info for:
  • Developer level getting started instructions
  • Software pre-requisites, Python 2.7, Java 6, etc.
  • Instructions for running unit tests
  • Initial install instructions
  • Documentation & Usage examples

Further help

Creative Commons License
Open Planets Foundation Development Guide by Open Planets Foundation is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.