Skip to content

Git Engineering Standard

This standard defines the repository model, branching, and versioning for the Bluefly ecosystem.

Related: Git Discipline, Git Completion Contract (ES-GITCC), Factory Operating Contract.

Repository Model

Every project uses:

main
release/v0.N.x
feature/*
fix/*
chore/*

N is the current semantic MINOR line. The active line today is release/v0.1.x. That branch stays the feature target until Thomas explicitly starts the next minor (release/v0.2.x).

Branch Role
main Latest stable line. Deployable. Receives release/v0.N.x only through the human promotion gate.
release/v0.N.x Active integration line. All normal feature/fix/chore work targets it.
feature/* fix/* chore/* Temporary work branches. Merge to release/v0.N.x only.

Remote authority: GitLab, reached through the governed gitlab-bluefly SSH alias. See Git Discipline Standard §7.

Never:

feature → main
fix → main
chore → main
main → release/v0.N.x

Branching & Merging

  • No rebase. Git Discipline forbids rebase, amend, and force-push. Forward-only history.
  • Merge strategy: Fast-forward or merge commits with detailed messages. Project squash policy is GitLab project settings, not an agent rewrite of history.
  • Feature MRs target release/v0.N.x, never main. A green MR is not done until merged. Agents merge when CI, required review, conflicts, and acceptance pass. Do not ask Thomas to merge ordinary feature work.
  • Promotion MRs are release/v0.N.x → main. Exactly one active promotion MR per project per active release line. Automation may create and update it. Automation must not merge it. AUTO_MERGE_RELEASE_TO_MAIN=NO.
  • See Git Completion Contract.

Releases & Versioning

Semantic Versioning. Only PATCH increments automatically inside a release line.

AUTOMATIC_MAJOR_BUMP=NO
AUTOMATIC_MINOR_BUMP=NO
AUTOMATIC_PATCH_BUMP=YES
DEV_SEQUENCE_AUTOMATIC=YES

Thomas creates release/v0.2.x when he starts the next minor. Automation must never independently mint 0.2.0.

Development sequence

Every successful merge into release/v0.N.x publishes a development build for projects that produce artifacts.

Canonical emitted form (git tags, npm, and any SemVer-compatible registry):

0.1.5-dev.1
0.1.5-dev.2
0.1.5-dev.3

Semantic rule (punctuation is secondary to this sequence):

main = v0.1.4
release changes = 0.1.5-dev.1, 0.1.5-dev.2, 0.1.5-dev.3
promotion = v0.1.5
next release change = 0.1.6-dev.1

Do not emit 0.2.0 from this line. Do not invent a parallel dev1 / dev2 dialect in consumer YAML.

Composer cannot publish a numbered -dev.N stability suffix. Composer consumers use the existing Bluefly equivalent: branch package dev-release/v0.N.x (moving channel), not a version-only commit. Drupal modules/recipes/site templates follow that Composer channel. The git tag / npm form remains 0.1.5-dev.N.

Derive dev.N from durable GitLab / package / tag state. Deterministic, race-safe, rebuild-safe. Overlapping release pipelines must not publish the same development version. Serialize versioning in GitLab CI (resource_group). Do not calculate the sequence from local worktree state. Do not commit version-only churn (0.1.5-dev.2 → 0.1.5-dev.3).

One implementation: blueflyio/gitlab_components. Consumers include the shared component. Do not reimplement the sequence per project.

Promotion

When Thomas authorizes release/v0.N.x → main:

  1. Stable patch is the promoted development candidate (0.1.5-dev.7 → 0.1.5).
  2. Do not rebuild materially different source. The stable package corresponds to the tested release SHA.
  3. Publish the stable package, tag v0.1.5, publish release metadata.
  4. Reset the next development target to the next patch (0.1.6-dev.1).
  5. Continue using release/v0.1.x. Do not create release/v0.2.x automatically.

Tagging after a governed promotion merge is automatic. That is not a second human click. The human gate is the promotion MR. Deploy jobs remain separately gated. STABLE_TAG_MATCHES_TESTED_RELEASE_SHA=YES.

Keep the single promotion MR current with a machine-generated section. Do not require a human to maintain this body:

RELEASE_BRANCH=
RELEASE_SHA=
TARGET_BRANCH=main
CURRENT_STABLE_TAG=
TARGET_STABLE_TAG=
CURRENT_DEV_TAG=
DEV_BUILDS=
INCLUDED_MRS=
INCLUDED_BEADS=
PACKAGE_TEST=
CONSUMER_TEST=
CI=
BLOCKERS=

Shared CI owner

Implement this lifecycle once in blueflyio/gitlab_components. Do not grow unique release YAML per consumer project.

CUSTOM_RELEASE_CI_PER_PROJECT=NO
SHARED_RELEASE_COMPONENT=gitlab_components

Agent Behavior

For agent-specific execution rules and the hard completion law, see Git Discipline and Git Completion Contract (ES-GITCC). Docs agents are in scope.

Technical Specifications

For detailed repository governance standards, workflows, and technical specifications, see: