← Back to Index

Architecture · ops.tradeit.gg

Development Cycle and Release Process

---

Purpose

Define how work moves from task pickup to production using our Git Flow process.

---

Branch Model

Permanent branches

• master

Production branch. Releases and hotfixes are merged here and tagged.

• develop

Main integration branch for ongoing work. Features and releases start from here, and completed work merges back here.

Working branches

• feature/<name>

Used for new functionality. Created from develop and merged back into develop.

• bugfix/<name>

Used for non-production bug fixes that should go into the next release. In our flow, bugfix branches follow the same lifecycle as features: branch from develop, PR into develop, QA, then release with the next version.

• release/<version>

Used to prepare a production release. Created from develop. When finished, it is merged into master, tagged, and back-merged into develop.

• hotfix/<version>

Used only for urgent production fixes. Created from master, then merged back into both master and develop, with a tag on master.

---

Development Cycle

1. ToDo

Task is defined and ready to be picked up.

2. In Development

Create a branch from develop.

For a feature:

git flow feature start <name>

For a bugfix in the next normal release:

git checkout develop
git checkout -b bugfix/<name>

Work done in this stage:

• implement the change
• commit using semantic commit messages
• push the branch
• keep scope limited to the task

Optional publish for collaboration:

git flow feature publish <name>

3. PR in Review

Open a pull request into develop.

• feature/<name> → develop
• bugfix/<name> → develop

If review requests changes, move back to In Development on the same branch.

4. PR Approved

Code review passed. The branch is ready for QA validation.

5. QA - Feature Staging

Deploy the branch to feature staging and validate it.

If QA fails:

• return to In Development
• continue on the same feature/* or bugfix/* branch
• update the PR as needed

If QA passes:

• merge into develop

6. Merge to Develop

After QA approval, merge the PR into develop.

This is the point where the work becomes part of the next release candidate.

7. Ready for Prod

Once the required set of features and bugfixes is in develop, create a release branch.

git flow release start <version>

Optional publish:

git flow release publish <version>

8. Release QA / Hardening

QA validates the release/<version> branch.

Only release-safe changes go here, such as:

• final bug fixes
• version updates
• release notes
• config or metadata adjustments

9. Production Release

When release QA passes, finish the release:

git flow release finish <version>
git push origin --tags

This does the following:

• merges release/<version> into master
• tags the release
• back-merges it into develop
• removes the release branch

---

Emergency Production Fixes

If production is broken, do not open a normal bugfix branch from develop.

Use a hotfix from master:

git flow hotfix start <version>

After the fix and QA:

git flow hotfix finish <version>
git push origin --tags

This does the following:

• merges the hotfix into master
• tags the hotfix release
• back-merges it into develop
• removes the hotfix branch

---

When to Use Each Branch Type

Use feature/* when

• adding new functionality
• changing behavior intentionally
• building a planned enhancement

Use bugfix/* when

• fixing a bug that is not yet a production emergency
• the fix should ship in the next planned release
• the work should follow the normal develop → release flow

Use hotfix/* when

• production is broken now
• the fix must go straight toward production
• waiting for the next regular release is not acceptable

---

Semantic Commit Standard

We use Conventional Commits for semantic commit messages.

Format:

<type>[optional scope]: <description>

Common types

• feat: new feature
• fix: bug fix
• refactor: internal code change without behavior change
• test: tests added or updated
• docs: documentation only
• chore: maintenance, tooling, or dependency work
• perf: performance improvement
• ci: CI/CD changes
• build: build or packaging changes

Breaking changes

Use ! after the type or scope, or add a BREAKING CHANGE: footer.

Examples:

feat(inventory): add delayed refresh after trade completion
fix(auth): handle expired steam session correctly
refactor(opensearch): simplify item query builder
test(trade): add coverage for escrow timeout flow
chore(deps): bump datadog library
feat(api)!: remove deprecated inventory response fields

Commit rules

• one commit should represent one logical change
• use imperative style
• keep the description short and specific
• do not use vague messages like fix stuff or changes
• prefer fix: for bugs and feat: for behavior additions

---

Minimal Working Examples

Normal feature

git checkout develop
git pull origin develop
git flow feature start inventory-resync

git commit -m "feat(inventory): add resync endpoint"

# open PR to develop
# QA on feature staging
# merge PR to develop

git flow release start 1.24.0
# release QA
git flow release finish 1.24.0
git push origin --tags

Normal bugfix for next release

git checkout develop
git pull origin develop
git checkout -b bugfix/staging-login-loop

git commit -m "fix(auth): stop redirect loop on staging"

# open PR to develop
# QA on feature staging
# merge PR to develop

git flow release start 1.24.1
# release QA
git flow release finish 1.24.1
git push origin --tags

Emergency production hotfix

git checkout master
git pull origin master
git flow hotfix start 1.24.2

git commit -m "fix(payment): handle provider timeout fallback"

# QA the hotfix
git flow hotfix finish 1.24.2
git push origin --tags

---

Summary

• feature/* and bugfix/* are normal develop-based work branches
• both go through development, review, QA, and merge into develop
• release/* is created from develop when a version is ready
• hotfix/* is only for urgent production issues and starts from master
• commit messages must follow Conventional Commits

---

ops.tradeit.gg — Internal Engineering Docs