Skip to main content

Git Workflow Guide

This document outlines the professional branching and release strategy for Elo Orgânico, combining the structural discipline of Git Flow with the collaboration power of the GitHub CLI (gh).

Branching Model​

We follow the standard Git Flow model to ensure the stability of our production code, adapted for our monorepo structure.

BranchPurposeStability
mainProduction releases. Every commit is a tagged release.Ultra Stable
developNext release development. Integration branch.Stable
feature/*New features or UI changes. Branch off develop.Experimental
bugfix/*Bug fixes for the next development cycle.Experimental
release/*Preparation for a new production release.Final Polish
hotfix/*Critical bug fixes for the production version.Urgent
support/*Long-term support branches for older major releases.Stable

Git Flow CLI Configuration​

Our local repository is configured with the following prefixes and tag rules:

Branch name for production releases: main
Branch name for "next release" development: develop
Feature branch prefix: feature/
Bugfix branch prefix: bugfix/
Release branch prefix: release/
Hotfix branch prefix: hotfix/
Support branch prefix: support/
Version tag prefix: v

Tooling Requirements​

To follow this workflow efficiently, we recommend:

  1. Git Flow CLI (AVH Edition): Usually included in Git for Windows or available via gitflow package.
  2. GitHub CLI (gh): Used for Pull Requests, status monitoring, and official releases.

Commit Standards (Conventional Commits)​

To maintain a clean and automated history, all commits must follow the Conventional Commits specification.

Format: <type>(<scope>): <description>

Types​

  • feat: A new feature (correlates with MINOR in SemVer).
  • fix: A bug fix (correlates with PATCH in SemVer).
  • docs: Documentation only changes.
  • style: Changes that do not affect the meaning of the code (white-space, formatting, etc).
  • refactor: A code change that neither fixes a bug nor adds a feature.
  • perf: A code change that improves performance.
  • test: Adding missing tests or correcting existing tests.
  • chore: Changes to the build process or auxiliary tools/libraries.

Monorepo Scopes​

Use the context or package name as the scope:

  • instance: Changes to the Community Instance apps or core.
  • portal: Changes to the Global Portal apps or core.
  • core: Changes to shared domain logic.
  • studio: Design tokens, assets, or Penpot configuration.
  • tools: MCP servers, scripts, or infrastructure.
  • deps: Dependency updates (managed via catalogs).

Example: feat(instance): add Pix payment reconciliation to checkout

Contribution Workflow​

1. Starting a New Feature​

Always branch off from develop.

git flow feature start my-awesome-feature

2. Collaborating and Proposing Changes​

Instead of merging locally, we use Pull Requests for code review and CI validation.

  1. Push your branch: git push -u origin feature/my-awesome-feature
  2. Create a Pull Request: 
    gh pr create --base develop --fill --web
    Use --fill to automatically use your commit messages for the PR description.

3. Senior Merge Strategy (Squash & Merge)​

To keep the develop history clean and meaningful, we use Squash Merges. This combines all commits from a feature branch into a single, well-described commit in develop.

  • Action: Merge via GitHub UI or CLI using the squash method.
  • CLI Command: gh pr merge --squash --delete-branch

Release & Versioning Workflow (Changesets)​

We use Changesets combined with GitHub Actions to automate our versioning, changelog compilation, and release Pull Requests. Developers do not bump package versions manually in package.json files.

1. Generating a Changeset (Local)​

When your feature or bug fix is ready and before opening a Pull Request:

  1. Run the interactive changeset tool from the repository root: 
    pnpm version:changeset
  2. Select the package(s) that were modified using the spacebar.
  3. Choose the appropriate SemVer bump level (Major for breaking changes, Minor for new backwards-compatible features, or Patch for bug fixes).
  4. Provide a clear, technical description of the change (in English, conforming to our commit standards).
  5. A temporary markdown file will be created under the .changeset/ directory (e.g., .changeset/warm-dogs-run.md).
  6. Commit this markdown file alongside your code and push it with your feature branch.
Keep Changesets Small

Create one changeset per isolated change. If a feature branch has multiple independent fixes or additions, you can run pnpm version:changeset multiple times to generate separate notes for each.

2. Automated Versioning Pipeline (GitHub Actions)​

Our CI/CD workflow handles the version bumping automatically when code is integrated:

  1. Pull Request & Integration: Developers open a Pull Request targeting the develop branch.
  2. Merge to develop: Once approved and merged into develop, the Manage Version Bumps and Releases GitHub Action is triggered.
  3. Release PR Generation:
    • The workflow parses the .changeset/*.md files present in the branch.
    • It calculates the new versions, consumes (deletes) the temporary changeset markdown files, bumps the respective package.json files, and updates the local package changelogs.
    • It automatically commits these changes and creates (or updates) an open Pull Request on GitHub named chore(release): version packages targeting develop.

3. Finalizing the Release (Maintainers Only)​

To publish and finalize the release:

  1. Open the automated Pull Request chore(release): version packages in GitHub.
  2. Review the compiled version changes and changelogs.
  3. Merge the Pull Request into develop. Because the changeset files have already been consumed and deleted, merging this PR consolidates the bumped package versions in the repository.
No Manual Version Bumps

Never edit the "version" field in a package's package.json manually during a normal feature branch. Always rely on pnpm version:changeset and let the GitHub Action pipeline manage the releases.

Critical Fixes (Hotfixes)​

If a bug is found in production:

  1. git flow hotfix start fix-crash
  2. Apply the fix and finish: git flow hotfix finish fix-crash
  3. Sync both main and develop.

Prohibited Practices​

  • No direct commits to main or develop: Always use feature branches and PRs.
  • No Force Pushes: Unless on your own isolated feature branch and required for a rebase.
  • No Dirty Merges: Avoid merging main back into feature/*. Always rebase onto develop if your feature branch becomes outdated.

Adherence to this workflow ensures a clean history and high-quality software distribution.