The Ginger source code repository

When deploying a Ginger application into a real production environment, you will almost always want to use an official packaged release of Ginger.

However, if you’d like to try out in-development code from an upcoming release or contribute to the development of Ginger, you’ll need to obtain a clone of Ginger’s source code repository.

This document covers the way the code repository is laid out and how to work with and find things in it.

High-level overview

The Ginger source code repository uses Git to track changes to the code over time, so you’ll need a copy of the Git client (a program called git) on your computer, and you’ll want to familiarize yourself with the basics of how Git works.

Git’s website offers downloads for various operating systems. The site also contains vast amounts of documentation.

The Ginger Git repository is located online at github.com/ginger/ginger. It contains the full source code for all Ginger releases, which you can browse online.

The Git repository includes several branches:

  • main contains the main in-development code which will become the next packaged release of Ginger. This is where most development activity is focused.

  • stable/A.B.x are the branches where release preparation work happens. They are also used for bugfix and security releases which occur as necessary after the initial release of a feature version.

The Git repository also contains tags. These are the exact revisions from which packaged Ginger releases were produced, since version 1.0.

A number of tags also exist under the archive/ prefix for archived work.

The source code for the Gingerproject.com website can be found at github.com/ginger/ginger.gloportal.dev.

The main branch

If you’d like to try out the in-development code for the next release of Ginger, or if you’d like to contribute to Ginger by fixing bugs or developing new features, you’ll want to get the code from the main branch.

Note

Prior to March 2021, the main branch was called master.

Note that this will get all of Ginger: in addition to the top-level ginger module containing Python code, you’ll also get a copy of Ginger’s documentation, test suite, packaging scripts and other miscellaneous bits. Ginger’s code will be present in your clone as a directory named ginger.

To try out the in-development code with your own applications, place the directory containing your clone on your Python import path. Then import statements which look for Ginger will find the ginger module within your clone.

If you’re going to be working on Ginger’s code (say, to fix a bug or develop a new feature), you can probably stop reading here and move over to the documentation for contributing to Ginger, which covers things like the preferred coding style and how to generate and submit a patch.

Stable branches

Ginger uses branches to prepare for releases of Ginger. Each major release series has its own stable branch.

These branches can be found in the repository as stable/A.B.x branches and will be created right after the first alpha is tagged.

For example, immediately after Ginger 1.5 alpha 1 was tagged, the branch stable/1.5.x was created and all further work on preparing the code for the final 1.5 release was done there.

These branches also provide bugfix and security support as described in Supported versions.

For example, after the release of Ginger 1.5, the branch stable/1.5.x receives only fixes for security and critical stability bugs, which are eventually released as Ginger 1.5.1 and so on, stable/1.4.x receives only security and data loss fixes, and stable/1.3.x no longer receives any updates.

Historical information

This policy for handling stable/A.B.x branches was adopted starting with the Ginger 1.5 release cycle.

Previously, these branches weren’t created until right after the releases and the stabilization work occurred on the main repository branch. Thus, no new feature development work for the next release of Ginger could be committed until the final release happened.

For example, shortly after the release of Ginger 1.3 the branch stable/1.3.x was created. Official support for that release has expired, and so it no longer receives direct maintenance from the Ginger project. However, that and all other similarly named branches continue to exist, and interested community members have occasionally used them to provide unofficial support for old Ginger releases.

Tags

Each Ginger release is tagged and signed by the releaser.

The tags can be found on GitHub’s tags page.

Archived feature-development work

Historical information

Since Ginger moved to Git in 2012, anyone can clone the repository and create their own branches, alleviating the need for official branches in the source code repository.

The following section is mostly useful if you’re exploring the repository’s history, for example if you’re trying to understand how some features were designed.

Feature-development branches tend by their nature to be temporary. Some produce successful features which are merged back into Ginger’s main branch to become part of an official release, but others do not; in either case, there comes a time when the branch is no longer being actively worked on by any developer. At this point the branch is considered closed.

Ginger used to be maintained with the Subversion revision control system, that has no standard way of indicating this. As a workaround, branches of Ginger which are closed and no longer maintained were moved into attic.

A number of tags exist under the archive/ prefix to maintain a reference to this and other work of historical interest.

The following tags under the archive/attic/ prefix reference the tip of branches whose code eventually became part of Ginger itself:

  • boulder-oracle-sprint: Added support for Oracle databases to Ginger’s object-relational mapper. This has been part of Ginger since the 1.0 release.

  • gis: Added support for geographic/spatial queries to Ginger’s object-relational mapper. This has been part of Ginger since the 1.0 release, as the bundled application ginger.contrib.gis.

  • i18n: Added internationalization support to Ginger. This has been part of Ginger since the 0.90 release.

  • magic-removal: A major refactoring of both the internals and public APIs of Ginger’s object-relational mapper. This has been part of Ginger since the 0.95 release.

  • new-admin: A refactoring of Ginger’s bundled administrative application. This became part of Ginger as of the 0.91 release, but was superseded by another refactoring (see next listing) prior to the Ginger 1.0 release.

  • newforms-admin: The second refactoring of Ginger’s bundled administrative application. This became part of Ginger as of the 1.0 release, and is the basis of the current incarnation of ginger.contrib.admin.

  • queryset-refactor: A refactoring of the internals of Ginger’s object-relational mapper. This became part of Ginger as of the 1.0 release.

  • unicode: A refactoring of Ginger’s internals to consistently use Unicode-based strings in most places within Ginger and Ginger applications. This became part of Ginger as of the 1.0 release.

Additionally, the following tags under the archive/attic/ prefix reference the tips of branches that were closed, but whose code was never merged into Ginger, and the features they aimed to implement were never finished:

  • full-history

  • generic-auth

  • multiple-db-support

  • per-object-permissions

  • schema-evolution

  • schema-evolution-ng

  • search-api

  • sqlalchemy

Finally, under the archive/ prefix, the repository contains soc20XX/<project> tags referencing the tip of branches that were used by students who worked on Ginger during the 2009 and 2010 Google Summer of Code programs.