Development Workflow

1. Introduction

This guide describes the development workflow for Event and Membership Management projects. We follow the GitFlow branching model, automated through the GitFlow Maven Plugin.

1.1. GitFlow Origins

GitFlow was originally conceived by Vincent Driessen in his influential 2010 blog post "A successful Git branching model".

For an excellent introduction to GitFlow concepts with visual diagrams, see the Atlassian GitFlow Tutorial.

1.2. Core Principles

Stable develop

The develop branch should always be buildable with all tests passing
Production-ready main

The main branch contains only released, production-ready code
Feature isolation

New features are developed in isolated branches
Release preparation

Releases are prepared in dedicated branches for stabilization

2. Branch Strategy

main     ─────●───────────────────●──────────────────────●────►
              │                   ↑                      ↑
              │            release/1.2.0                 │
              │                   ↑                      │
              │                   │              release/1.3.0
              │                   │                      ↑
develop  ─────●───●───●───●───●───●───●───●───●───●───●──●───►
                  ↑   ↑   ↑
          feature/  feature/  feature/
          ADO-101   ADO-102   ADO-103

2.1. Branch Types

Branch Type Purpose Naming Convention

main

Production-ready releases

main (protected)

develop

Integration branch for features

develop (protected)

Feature

New functionality

feature/ADO-{id}-GitFlow development process for Event and Membership projects

Bugfix

Bug fixes for develop

bugfix/ADO-{id}-GitFlow development process for Event and Membership projects

Release

Release preparation

release/{version}

Hotfix

Emergency production fixes

hotfix/{version}

3. Feature Development

3.1. Creating a Feature Branch

# Ensure develop is up to date
git checkout develop
git pull origin develop

# Create feature branch
git checkout -b feature/ADO-123-add-user-authentication

3.2. Branch Naming Convention

feature/ADO-{work-item-id}-{brief-description}

  • Always reference the Azure DevOps work item ID

  • Use lowercase with hyphens

  • Keep the description brief but descriptive

Examples
feature/ADO-123-add-user-authentication
feature/ADO-456-refactor-payment-service
bugfix/ADO-789-fix-login-redirect

3.3. Commit Messages

ADO-{id}: Brief description (max 72 chars)

Optional longer explanation of:
- What changed
- Why it changed
- Notable implementation details
Examples
ADO-123: Add JWT authentication to login endpoint

Implement JWT-based authentication using Spring Security.
- Added JwtTokenProvider service
- Configured SecurityFilterChain
- Added login and refresh token endpoints

3.4. CI/CD During Feature Development

  • No CI during feature branch commits - Tests are not run on every push

  • Tests run when PR is created - Full test suite executes on PR creation/update

  • Merge requires passing tests - Unless overridden by an authorized person

3.5. Creating a Pull Request

When your feature is ready for review:

  1. Push your feature branch to origin

  2. Create a PR targeting develop

  3. Fill in the PR template with:

    • Summary of changes

    • Link to ADO work item

    • Testing performed

    • Checklist completion

4. Release Process

4.1. Overview

The release process follows these steps:

  1. Create release branch from develop

  2. Stabilize version - Remove -SNAPSHOT suffix

  3. Bump develop version - Increment to next -SNAPSHOT

  4. Polish release - Bug fixes, documentation updates

  5. Merge to main - Triggers release pipeline

  6. GitFlow finish - Merges back to develop, creates tag

4.2. Starting a Release

Using the GitFlow Maven Plugin:

mvn gitflow:release-start

This automatically:

  • Creates release/{version} branch from develop

  • Updates version to remove -SNAPSHOT (e.g., 1.2.0-SNAPSHOT → 1.2.0)

  • Updates develop to next -SNAPSHOT (e.g., 1.2.1-SNAPSHOT)

  • Pushes both branches

4.3. Release Branch Activities

During the release phase:

  • Bug fixes directly on release branch

  • Documentation updates (README, RELEASE.md)

  • Configuration adjustments

  • Each push triggers test pipeline

4.4. Completing a Release

When the release is ready, merge the PR to main. This triggers:

  1. Production build with prod Maven profile

  2. Docker image push to registry

  3. Helm chart package and push

  4. GitFlow release-finish workflow:

    • Merges release branch to main

    • Creates version tag

    • Merges any release changes back to develop

5. GitFlow Maven Plugin

5.1. Overview

The GitFlow Maven Plugin automates GitFlow operations, ensuring consistent version management and branch handling.

Best Practice: Configure the plugin in the parent POM to ensure consistency across all projects in the organization.

5.2. Plugin Configuration

Reference implementation from event/pom.xml:

<plugin>
  <groupId>com.amashchenko.maven.plugin</groupId>
  <artifactId>gitflow-maven-plugin</artifactId>
  <version>${gitflow-maven-plugin.version}</version>
  <configuration>
    <!-- Whether to print commands output into the console -->
    <verbose>false</verbose>
    <!-- Whether to fetch remote branch and compare it with the local one -->
    <fetchRemote>true</fetchRemote>
    <!-- Whether to call Maven install goal during the mojo execution -->
    <installProject>false</installProject>
    <!-- Whether to push to the remote for release/feature/hotfix start -->
    <pushRemote>true</pushRemote>
    <!-- Whether to skip changing project version on feature branches -->
    <skipFeatureVersion>true</skipFeatureVersion>

    <!-- CI-friendly versioning support -->
    <versionProperty>revision</versionProperty>
    <skipUpdateVersion>true</skipUpdateVersion>

    <!-- Git flow configuration -->
    <gitFlowConfig>
      <productionBranch>main</productionBranch>
      <developmentBranch>develop</developmentBranch>
      <featureBranchPrefix>feature/</featureBranchPrefix>
      <releaseBranchPrefix>release/</releaseBranchPrefix>
      <hotfixBranchPrefix>hotfix/</hotfixBranchPrefix>
      <supportBranchPrefix>support/</supportBranchPrefix>
      <versionTagPrefix />
      <origin>origin</origin>
    </gitFlowConfig>

    <!-- Git commit messages -->
    <commitMessages>
      <featureStartMessage>Feature start. Set feature version to @{version}.</featureStartMessage>
      <featureFinishMessage>Feature finished. Development version updated to @{version}.</featureFinishMessage>
      <hotfixStartMessage>Hotfix start. Set hotfix version to @{version}.</hotfixStartMessage>
      <hotfixFinishMessage>Hotfix finished. Development version updated to @{version}.</hotfixFinishMessage>
      <releaseStartMessage>Release start. Set release version to @{version}.</releaseStartMessage>
      <releaseFinishMessage>Release finished. Development version incremented to @{version}.</releaseFinishMessage>
      <releaseFinishMergeMessage>Released v@{version}</releaseFinishMergeMessage>
      <tagHotfixMessage>Tag hotfix @{version}</tagHotfixMessage>
      <tagReleaseMessage>Tag release @{version}</tagReleaseMessage>
    </commitMessages>
  </configuration>
</plugin>

5.3. Key Configuration Options

Option Description

versionProperty=revision

Uses CI-friendly ${revision} property for versioning

skipFeatureVersion=true

Don’t modify version when creating feature branches

pushRemote=true

Automatically push branches and tags to remote

skipUpdateVersion=true

Works with flatten-maven-plugin for CI-friendly builds

5.4. Plugin Goals

Goal Description

gitflow:feature-start

Create a new feature branch from develop

gitflow:feature-finish

Merge feature branch back to develop

gitflow:release-start

Create release branch, update versions

gitflow:release-finish

Merge to main, tag, merge back to develop

gitflow:hotfix-start

Create hotfix branch from main

gitflow:hotfix-finish

Merge hotfix to main and develop

5.5. CI-Friendly Versioning

The plugin works with Maven’s CI-friendly versioning and the flatten-maven-plugin:

<properties>
  <revision>1.3.2-SNAPSHOT</revision>
</properties>

<version>${revision}</version>

This allows the version to be set dynamically during CI builds while the POM remains unchanged.

6. Hotfix Process

Hotfixes are emergency fixes applied directly to production.

6.1. Creating a Hotfix

mvn gitflow:hotfix-start -DhotfixVersion=1.2.1

This:

  • Creates hotfix/1.2.1 branch from main

  • Updates version to 1.2.1

6.2. Completing a Hotfix

mvn gitflow:hotfix-finish

This:

  • Merges hotfix to main

  • Creates version tag

  • Merges hotfix to develop

  • Deletes hotfix branch

TODO: GitHub Actions automation for the hotfix workflow has not yet been implemented. Currently, hotfixes are performed manually using the GitFlow Maven Plugin.

7. Version Management

7.1. Version Lifecycle

Branch Version Format Example

develop

X.Y.Z-SNAPSHOT

1.3.0-SNAPSHOT

release/X.Y.Z

X.Y.Z

1.2.0

main (after release)

X.Y.Z (tagged)

1.2.0

develop (after release)

X.Y.(Z+1)-SNAPSHOT

1.3.0-SNAPSHOT

7.2. Version Bumping

When a release starts:

  • Release branch: 1.2.0-SNAPSHOT → 1.2.0

  • Develop branch: 1.2.0-SNAPSHOT → 1.3.0-SNAPSHOT

7.3. Semantic Versioning

Follow Semantic Versioning:

MAJOR

Breaking changes to public API
MINOR

New functionality, backwards compatible
PATCH

Bug fixes, backwards compatible

8. CI/CD Integration

For detailed information on how the development workflow integrates with CI/CD pipelines, see GitHub Actions CI/CD Architecture.

8.1. PR Pipelines

  • PRs to develop trigger the test pipeline

  • All tests must pass before merge (unless overridden)

  • Path filtering ensures only relevant tests run

8.2. Develop Push Pipeline

Pushes to develop trigger:

  • Frontend and backend tests (based on changes)

  • Maven packaging

  • Docker image build and push

  • Dependency graph submission

8.3. Main Push Pipeline (Release)

Pushes to main trigger:

  • Production build with prod profile

  • Docker image push

  • Helm chart package and push

  • GitFlow release-finish automation

9. Best Practices

9.1. Do’s

  • ✅ Keep feature branches short-lived (days, not weeks)

  • ✅ Update from develop regularly to avoid merge conflicts

  • ✅ Write meaningful commit messages with ADO references

  • ✅ Run tests locally before pushing

  • ✅ Request code reviews promptly

9.2. Don’ts

  • ❌ Don’t commit directly to main or develop

  • ❌ Don’t merge PRs with failing tests

  • ❌ Don’t leave feature branches open for extended periods

  • ❌ Don’t force push to shared branches

  • ❌ Don’t skip the release stabilization phase

10. Related Documentation

11. External References