Skip to content

GitHub repository workflow

Naming convention

New repositories use the product identifier defined in Naming conventions, for example cus-acme-crm or int-reporting. Existing repositories are not renamed only to satisfy this policy.

Each repository must have:

  • a concise README.md covering purpose, local setup, application ownership, and deployment target;
  • .env.example listing required variables without values or secrets;
  • a lockfile committed with its package manager;
  • CI validation under .github/workflows/; and
  • a clear owner: a named person or the Engineering team.

Branching strategy

DoWEB uses a protected integration-and-release flow:

  • develop is the active integration branch. Everyday completed work is merged here first.
  • main contains only production-ready releases. A push to main deploys to production through Dokploy.
  • Work branches start from develop and are short-lived.
  • Use feat/, fix/, chore/, docs/, or refactor/, followed by a concise kebab-case description. Add a work-item identifier first when one exists: feat/123-customer-import.
  • Merge a work branch into develop with squash and merge after checks and review pass.
  • When develop is ready to release, open a pull request from develop to main. Use a merge commit for this release pull request so Git records the release boundary.
  • Delete work branches after merge. main and develop are permanent branches; do not force-push either one.

Use Conventional Commit messages for commits and pull-request titles:

feat(api): add customer import
fix(web): handle expired session
chore(deps): update pnpm

Production hotfixes

For an urgent production fix, create hotfix/<short-description> from main, then open a pull request to main. Once merged and deployed, merge or cherry-pick the same fix into develop immediately so the branches do not diverge.

Branch protection rules

Every production repository protects both develop and main with these minimum rules:

  • require a pull request before merge;
  • require one approval from another DoWEB contributor;
  • require the CI validation workflow to pass;
  • require resolved review conversations;
  • prohibit force-pushes and branch deletion; and
  • enforce the rule for repository administrators.

Emergency changes

For an active production incident, a maintainer may merge an emergency fix without a review when waiting would materially increase customer impact. The maintainer must still ensure CI passes where possible, document the reason in the pull request, and arrange a retrospective review on the next working day.

Ownership and exceptions

The repository owner is responsible for dependency updates, access, deployment configuration, and the accuracy of the README. If a project cannot follow this standard, add a short ## Deviations from DoWEB standards section to its README explaining the reason, owner, and review date.