GitHub Guide

Version 10 by Carl Wilson
on Mar 06, 2013 18:37.

<< Changes from 9 to 10

compared with

Current by Carl Wilson
on May 08, 2013 08:42.

Key

This line was removed.

This word was removed. This word was added.

This line was added.

Changes (4)

View Page History

...

{toc}
h1. Git & GitHub
The OPF strongly encourages developers to use [GitHub | http://github.com] 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 | http://git-scm.com] 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 | http://help.github.com].
* They provide a [web based API | http://developer.github.com/] for automating development tasks.

h1. 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/]

h2. The OPF GitHub Organisation
The OPF has a [GitHub organisation page| https://github.com/openplanets], 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 | http://github.com].
{tip:title=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.
{tip}

h2.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.

h1.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.
h2.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.
h2.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

h2. 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.

{anchor:newrepo}

h2.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.

...

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.
{tip}

{anchor:opfyaml}

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

...

{info:title=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.
{info}
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| http://yaml.org/] provides more information, and [this tutorial | http://www.keleshev.com/yaml-quick-intoduction] 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.
{code:title=.opf.yml Project Description File}
# Specification for .opf.yml file
#
# MANDATORY
# The name of the software project, NOT just the higher level project
# e.g. Jpylyzer, scape-toolwrapper
name: Project Name

# MANDATORY
# The project or organisation responsible for repository
# e.g.SCAPE, OPF, or The British Library
vendor: Vendor Name

# MANDATORY
# The name and email address of the project maintainer.
# Initially set to individual who requested the repository
maintainer:
name: Maintainer Name
email: project(DOT)maintainer(AT)project(DOT)office

# All the remaining fields are optional, please supply any info known

# Details of the deployment platform
# e.g. Java, Python, Tomcat....
platform: Platform details

# Target OS if OS specific
# e.g. Windows 7, linux, MacOS
operating-system: Name of target Operating System

# URL of download page, if one exists
download: http://example.org

# List of developers working on the project, repeat all three lines of the
# developer list item to add details for multiple developers.
# There's no need to repeat the project maintainer here
developers:
- developer:
name: Developer Name
email: developer(AT)example(DOT)org

# URL of software web site home page, if one exists

homepage: http://example.org
{code}

{anchor:license}

h3. License
{tip:title=State Your License}

...

{tip}
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.

{anchor:readme}

h3. 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|https://help.github.com/articles/create-a-repo]. The README.md can be edited as a plain text file, but GitHub also supports [GitHub flavoured Markdown | https://help.github.com/articles/github-flavored-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:

{info:title=Example Mission Statement}
{quote}
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!
{quote}
{info}
{note:title=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
{note}

h1. 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]

{html}
<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-sa/3.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" href="http://purl.org/dc/dcmitype/Text" property="dct:title" rel="dct:type">Open Planets Foundation Development Guide</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="http://openplanetsfoundation.org" property="cc:attributionName" rel="cc:attributionURL">Open Planets Foundation</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
{html}