# Heptapod contributor documentation

## Branches layout

### Rails application

The Rails application can be thought of as the main
[Heptapod repository](https://foss.heptapod.net/heptapod/heptapod).

Heptapod releases are based onto GitLab stable versions, which themselves are
usually taken from a Git branch that has diverged from the GitLab master branch,
and aren't merged back when end of life is reached for these versions.

This means that we can't just start from our latest release and build on top
of that.

- `heptapod`, the main development branch, derives from a common ancestor
  of GitLab's master and its stable release. Example: `v12.2.0.pre`. There
  is no upstream Docker image for these.
- `heptapod-x-y` bears the Heptapod x.y.0 version and its release
  candidates. It is initialized by merging the target GitLab stable release
  and `heptapod`. Example: the first commit of `heptapod-0-12` is the
  merge of `heptapod` and `v12.2.12`
- `heptapod-stable`, support branch for the current stable series of Heptapod
  versions. It is derived from `heptapod` before we bump the upstream
  GitLab version in `heptapod`, and is *not* merged with the target GitLab
  stable release.

#### Process: release for Heptapod x.y.z, with z>0

- merge of `heptapod-stable` into `heptapod-x-y`
- testing on `heptapod-x-y`, first from source, then with the Docker image.
- release from `heptapod-x-y`
- merge of `heptapod-stable` into `heptapod`, for the future new minor release.

#### Process release for Heptapod x.y.0

- merge of `heptapod-stable` into `heptapod`, meaning that the new minor version
  will have all the fixes done in the previous stable branch
- merge back of `heptapod` into heptapod-stable`, this is a new start for
  the permanent stable branch. At this point, the previous `heptapod-x-(y-1)`
  branch is essentially dead (urgent critical fixes can still be done, but
  they will require manual forward porting)
- creation of `heptapod-x-y` by merging `heptapod-stable` branch with
  the target GitLab stable release
- testing on `heptapod-x-y`, first from source, then with the Docker image.

### Heptapod Workhorse and Heptapod Shell

Heptapod Workhorse is mandatory since Heptapod 0.13

These two forked components have a branch layout simpler than the Rails
application, because their support branches in upstream GitLab tend to
diverge less from the ongoing master. Also, they are much smaller.

- `heptapod` is the main development branch for Heptapod
- `heptapod-x-y` is the support branch for Heptapod x.y, if needed. It's
  happened in the past that a given component would not need any modification
  for point releases, i.e., Heptapod x.y.z (with z>0).
- `default` is for converted upstream changesets only.
