Creating a new Google Code project

by Stuart Yeates and Ross Gardler on 6 March 2007 , last updated

Archived This page has been archived. Its content will not be updated. Further details of our archive policy.

Introduction

Google Code is a website which offers free hosting services for open source projects. It provides the core facilities required by a community-led open source project. This document is a basic introduction to getting started with Google Code project hosting.

Hosting service overview

The services provided by Google Code are:

authentication:
anyone with a valid google.com account can use their normal Google username and password to log into Google Code and access the functionality. This means that if you use any existing Google web services such as GMail or Calendar, you already have a Google Code account. You can control access to your project resources by adding members to your project using their google.com account.
version control:
Version control systems are used to track changes to project resources such as documentation and source code. Subversion (often abbreviated to SVN), Git and Mercurial are available for use in projects. The version control system is the key to managing changes in project resources over time, tracking contributions with respect to IPR management and collaboration between developers.
communications:
Mailing lists and forums are used for project communication. While Google Code does not include either, they can be linked to from the project. Google Groups, another member of the Google family, uses the same authentication system that Google Code uses. The great thing about Google Groups is that it can be used as a traditional mailing list, an online forum or an RSS feed; the choice is left up to the user. This flexibility maximises the chances that any given user will subscribe to the list.
wiki:
A wiki is provided for simple project documentation. The wiki provided is functional and flexible, but does not provide very elaborate functionality. It is not a substitute for a well-managed informational website, but it is a great resource for developer notes and a basic project website. One of the biggest advantages of the Google Code wiki over other project-hosting solutions is that you can edit the content via a web-based wiki editor or via the project repository. This makes access to and use of wiki files much more flexible.
issue tracking:
An issue tracker is provided that allows users to report ‘issues’, whether they be bug reports, feature requests, or installation problems.
downloads:
The downloads section is a simple area for storing files for download. These will usually be software releases and documentation packages.
feeds:
Comprehensive RSS and Atom feeds are provided to facilitate monitoring of the services and gadgets can be used in wiki pages to monitor external feeds.
group administration functions:
these include the management of project members and the configuration of the available tools.

Google also provides a number of other services that may be useful to projects hosted on Google Code, or even elsewhere. There is no requirement to use them, but it makes sense if you need these features, since your project members will already be signed in to their Google account and will therefore benefit from the Google single sign-on system.

Other useful services that can be linked to from your project site include:

calendar:
useful for tracking project releases, meetings and governance issues such as votes.
docs and spreadsheets:
sharing documents between project members for collaborative development is really easy using the docs and spreadsheets applications.
analytics:
Google Analytics may be enabled for the project in order to monitor web traffic.

Create the project

Creating a Google Code project is done using the online form.

It is worth noting that your project name will form part of the URL for your project development site, so be sure that the name you enter is the one you want.

Google also limits the number of licence options available to you. In their FAQ, they explain this decision as follows:

‘The open source community has been flooded with lots of nearly identical licenses. We’d like to see projects standardize on the most popular, time-tested ones. For that reason, we encourage projects that we host to use one of the licenses listed on our project creation page. The offered licenses offer enough diversity to meet most developer needs, while minimizing license proliferation.’

The licences selected by Google are broadly in line with the Open Source Initiative’s list of licences they believe to be ‘popular and widely used with strong communities’. There is also the optional facility to apply a separate, Creative Commons, licence to cover the non-code assets in the project.

Once you have submitted the details, a new project page will appear in the Google Code site at http://code.google.com/p//. This page will contain the information you provided in the registration screen. From this page you are able to view the various tools provided and, assuming you are an administrator (which you will be if you registered the project), you will be able to configure the behaviour of the tools for your project needs.

At this stage, it is worth putting a little more thought into the summary and description, since they are the first things potential users see when evaluating a project. The description should elaborate on the aims of the software and should contain high-level information written in non-technical language so that newcomers can easily see whether this project is likely to be of interest. It should also contain a brief technical overview, to allow specialists in the field to compare several projects to see which one is best suited to them. Finally, it should contain a candid evaluation of the state of the project. If the project is on the drawing board rather than in the deployment phase, users will appreciate knowing this up front, while developers will recognise they will be getting in on the ground floor and therefore may be able to influence important design decisions.

Create the mailing lists/groups

Mailing lists are the most important communication mechanism for community-led projects. In addition to one or more existing mailing lists, Google Code can be used with Google Groups, another of the Google family of applications. One of Google Groups’ most popular features is that subscribers can use it either as a mailing list or as a web forum. This is important, as it allows contributors to participate in a way that is most comfortable for them. Another important feature of Google Groups is that it can be used to provide an interface to an existing mailing list, so if you already have a mailing list in operation, then Google Groups can provide a convenient interface to it, together with Google’s excellent search capabilities.

If you already have a group or mailing list for your project, enter the address of a web page describing the list in the ‘discussion groups’ field. This will ensure that your mailing list information is displayed on your project’s Google Code page. You can enter more than one mailing list in the admin form; each of them will appear on the project page. Note that the page you enter must already exist; entering information into this field does not create the list for you.

You should also consider providing a mailing list address to receive activity notifications from Google Code. In this case you enter the email address rather than a website address. This means that interested parties are notified by email of new commits and issue tracker activity. Whether you send these notifications to the same list as that intended for discussion or whether you set up alternative lists really depends on the governance of your project. In consensus driven projects, such as those in the Apache Software Foundation, notifications will typically go to the open developer mailing list, whereas in more closed communities they will typically be sent to a closed list. Google Code allows you to use different lists for each type of notification. Note that for these mail notifications to work your mailing list must accept posts from @googlecode.com.

Issue tracker

The Google Code issue tracker allows users to report ‘issues’, whether they be bug reports, feature requests, or installation problems. The issue tracker is a public resource and anyone visiting the Google Code site is able to examine existing issues. However, a major drawback of Google Code is that users will need a Google account in order to add issues, add a comment to existing issues, or ‘vote’ for ones they feel are important. This may be a barrier towards people outside your initial project team to engage with the project via the issue tracker. In any case, this is a vital tool for communication between users and developers and should be utilised as a project-planning tool.

Using the tracker enables project management to prioritise, schedule, assign and document issues clearly. For many open source projects, issue trackers represent the collective memory of what problems have been encountered, by whom, whether they have been addressed, who is working on them, which future release will contain the changes required and how important users perceive each issue to be. This information has a host of technical, legal and administrative uses. Used well, an issue tracker is key to a project’s good management.

The issue tracker in Google Code is not as feature rich as some in the marketplace but does have reasonable customisation options. If your project is of a considerable size it could be argued that the Google Code tracker is insufficient. There are also concerns that the data in the tracker is not currently exportable, so if you move from Google Code in the future you may find it difficult to migrate your issue tracker content; though a limited facility to export data from the issue tracker is available, at present it seems to be limited just to the header information, not the content of the discussions. However, the issue tracker is quick and easy to set up and, perhaps most importantly for new users, it is simple, with none of the potentially distracting ‘power user’ features of some alternatives. A low barrier to entry for users wanting to report issues is vital to involving those users in your work. The Google Code issue tracker does a great job in this respect.

Version control

Google code offers Subversion, Git and Mercurial version control systems. These version control systems support distributed development and track line-by-line changes made to every file and document in the repository, tracking who made the change, when and why. This information is vital in tracking intellectual property rights (IPR) in your project but also allows you to easily manage different versions of your outputs and to correct mistakes easily.

The use of a public revision control system is critical to open source projects that wish to engage their user and developer community. It is through the version control system that cutting-edge users are able to get the latest development versions of your code and provides the code against which patches will be supplied.

It is beyond the scope of this document to describe the use of SVN in open source development. Detailed documentation on the use of Subversion can be found in the Subversion Book (see resources).

Wiki

The wiki provided by Google Code is somewhat limited when compared to some of the popular wiki software available. However, it has one considerable advantage over other wiki tools - it allows content in the wiki to be edited offline and then committed via SVN. This means that it is possible to use the wiki in a much more flexible way than is often possible with a web only interface. Of course, Google Code also provides a web interface.

Integration

Google appears to be improving the integration of Google Code’s tools. For example, a documented mechanism is provided to perform updates to the issue tracker by embedding commands in version control check-in comments. Such features are very useful in providing an audit trail in your project.

Other integration features tend to be undocumented and should be considered alpha (i.e. they may change). For example, issue tracker descriptions can contain references to wiki pages.

Unfortunately, Google does not publish an API for Google Code. This makes it difficult for third-party tools to integrate with the product. However, there are projects working towards creating a better development environment.

Licensing

By agreeing to the terms of service that Google presents on sign-up to Google Code, you grant Google rights to distribute any of the material you upload to your Google Code project. This does not change the ownership of the material, which will still be yours (if it was before).

On the project administration page there is a drop-down box to change the advertised licence of the project. This constrains a project to a small (but reasonable) subset of open source licences. It also allows one to apply a second, separate licence to the non-code assets in a project. Projects should be aware that changing a project’s licence is not as easy as changing the item in the drop-down box once there is content in the wiki and repository, since materials will have to be carefully relicensed. Therefore, careful consideration of the licence you choose during registration is important. If you would like assistance with choosing a licence, contact us at OSS Watch.

Alternatives and barriers to Google Code use

First and foremost, you need to be aware that your organisational policies may advise against (or even forbid) the use of non-approved third-party services. However, if you intend to open source your project and you wish to work towards true sustainability via the open source route, then it is important that your outputs are available to potential users and community members in an ongoing and sustainable way, even beyond your initial funding. In many cases, using an external facility, such as Google Code, will often be easier and cheaper than creating in-house services for hosting your outputs. OSS Watch will be able to liaise with your organisational policy makers in order to establish an acceptable and realistic policy for both your project and your organisation.

Assuming that there are no organisational barriers to the use of a third-party system, one must then choose a service to use. A wide range of commercial and not-for-profit services offer a comparable set of services to Google Code. Each offers a different set of services and a different set of conditions on use. They include SourceForge, GitHub, Savannah, GNA, BerliOS, TuxFamily, Debian Alioth. OSS Watch will be happy to help your project decide on the appropriate home for its outputs.

Many projects are initially associated with an institution, which may consider hosting these services internally. This gives the option of customisation of the tools with respect to the project needs. Such hosting has the additional effect of providing a clear link between the project and the host institution. Such an association may be a benefit or a restriction depending on the intentions of the project. For example, strong association with an institution may prevent some potential contributors from becoming involved, or it may be a mechanism by which the institution improves its brand in a given area. It also leaves the project at the mercy of a change of circumstance within the single institution.

Google Code is generally a good solution for your hosting needs. It is clean, comfortable to use and focussed. However, the requirement to have a Google account in order to interact with the project’s issue tracker can potentially be a barrier for people to engage with the project. Notwithstanding that Google Code is in general a good solution for a small to medium sized project that wishes to get up and running quickly and does not want to be confused by a wealth of tools that are not always necessary in a community led project.

The OSS Watch briefing note Avoiding abandon-ware: getting to grips with the open development method provides an overview of best practices that can be applied when undertaking open development using services such as Google Code.

Further reading

Google Code Links:

Other resources:

Alternatives to Google Code:

Related information from OSS Watch: