Technical infrastructure
The technical infrastructure required for hosting a free software project usually consists of various elements and tools that are often interlinked in complex ways. In this chapter we recommend some common tools and practices for using them in the sector.
A general principle that is spelt out in the measures in the chapter is that people who participate in a project must never be compelled to install proprietary software on their equipment.
Websites associated with the project
A typical software project might have two websites:
A development website for people contributing code or technical documentation to the project, whether they are hired by the City Council or not.
A website for users and participants in general. That includes people or organisations that might want to install and use the software outside the City Council but also people who are interested in the project even though they are not direct users of the software. On this website we need to facilitate and encourage people to participate in the project with contributions that are less (or not at all) technical: funding, user documents, pre-release testing, dissemination, translations and so on.
Usually both types of content are necessary but it is not always necessary to be in two separate places, with different domain names. In each project it leads, the City Council will have to assess to what extent the needs and mentalities of the two sets of people are different, therefore making it impossible for a single website model to accommodate both.
The section Code repository and version control explains how to set up the development site, the only one required from the outset. We can assess if there is also a need for a site geared towards other participant profiles as the project grows.
What is useful is for the project to have its own domain name (or a permanent URL under a City Council domain) from the outset. If necessary, this could be redirected to where the project website is.
Code repository and version control
A key element of the project development website is a code repository (public and under version control) which serves as a base for centralising modifications that form part of each new product release.
In the NewProduct
or Plugin
use-case, the City Council will have to create this repository.
In the case of an Integration
or Adaptation
, the Council will have its own copy (clone or fork) of the original (upstream) repository, where the documents corresponding to the modifications of interest will be centralised.
We will call this repository created by the City Council, which will be used for original product releases or to centralise the contributions to an external project, the main repository.
There could be many other public and private copies of the code.
The City Council is in the process of reconsidering the platform to be used to host things like a public facing code repository or an issue manager for every project. The first free software projects of the City Council have used GitHub, but now we want to transition to a free software solution. The many references to GitHub in the following sections are going to be replaced when a decision is reached. |
As is pointed out in the measures below, the main repository will be hosted at GitHub, a service that Git uses as a distributed version control system. The basic vocabulary and concepts for understanding how it works can be found at Version Control Vocabulary.
There are many viable and reasonable alternatives to GitHub, even some viable alternatives to Git as a version control program[.line-through], but GitHub offers enough advantages for it to be the default option:
-
Most developers are familiar with it and do not have to learn new tools and procedures ad-hoc for the project.
-
It launches the message that the project is open to collaboration.
-
It offers good integration with the rest of a product’s technical and social infrastructure: issue managing, continuous integration, development communication channels, etc.
-
It also enables (part of) a product’s documentation to be saved and displayed, which could be a wiki. The presentation of the information is sufficiently user-friendly for us to put off building a website for project users and participants in general.
-
It is the platform most widely used by free software code projects and provides a lot of exposure.
Any alternative has to offer similar guarantees with regard to durability and sustainability.
Drawback: GitHub is not free software.
Although it is a free service for a wide range of possible uses, not all the infrastructure code behind GitHub is open and ultimately that means being dependent on a company whose future development we cannot predict. In the future other options might appear that could make us reconsider recommending using GitHub as the default option.
Issue manager
One tool all free software projects need is an issue manager or bug tracker. At the City Council we assign it the following functions:
-
Provide notification of any defects detected (bugs tracked) by users and developers. Also to make their treatment, evolution and eventual solution transparent. It is important that the changes (commits) that solve a defect (bug) point it out in their message. GitHub has keywords for this.
-
Follow up tasks that are pending. This enables one or more commits to then be linked with the closing of an issue It is also possible to see who tasks have been assigned to and how they are prioritised. One option is to specify estimated completion dates. All this contributes to the transparency and traceability of the development process.
-
Follow up how the contributions of the different parts are managed by means of the pull request mechanism. The bug tracker could even be open to feature requests and the GitHub space could be used for publicly managing and prioritising.
It needs to be borne in mind that the bug tracker is not only important for the everyday work of developers but also that many project observers use it as a measure of how serious the project is.
This bug tracker has to be operational and public throughout the product’s useful life, i.e. after the contracts with the City Council have finished.
Internal and external communication channels
The first lines of communication between developers are the repository commit messages and the issue manager threads. Many technical decisions are taken in these threads but the discussions that take place in them should always be highly focused and strictly technical. When the area under discussion broadens out, it is necessary to resort to other channels.
Initially all new projects have to create a development mail list or a discussion forum, with public files. This is the channel through which the opinion of the different parties or individuals taking part in the project is sought and strategic decisions are taken.
At first there will not be much that separates the developers and first users or early adopters as regards concerns and language, the latter usually being highly motivated. Consequently, in many cases the same channel will suffice. Later it may be necessary to create specialised communication channels for different kinds of participants.
Depending on the nature and make-up of the team, it might be useful to have a chat room for more immediate communication. Either way, it would supplement the list or the forum, never replace it. The list or forum is where the whole history of the project (discussions, decisions, etc.) is recorded for reference, a very valuable asset for the whole project community, present and future.