Skip to content

20 — PR & contribution workflow

This doc describes the contribution workflow used by the team — branch naming, commit conventions, PR expectations, and review workflow. Conventions here are derived from observed git history and project files; verify with the team for anything marked as best-effort inference.

Branches

The repo has many long-lived branches. Observed canonical branches:

Branch Purpose
main Default base branch.
uat_app UAT environment branch. Recently merged into main. Likely the staging branch.
dev_app Dev environment branch. The Jenkinsfile in this repo deploys this branch. Engineers branch off of dev_app for feature work.
prod_* Several prod_* branches exist (e.g. prod_latest_4.8.23, prod_v20.7.23). Verify with the team which is currently the production branch.

Feature branches in remote origin follow a wide variety of naming styles — some examples from git branch -a:

  • BNIFLOW, CHATBOT_SEP, CRM_integration — UPPERCASE feature names
  • 14days_free_trial, Ai_suggestion_update — snake/spinal mix
  • fix/opt-upload-temp — slash-prefixed conventional
  • Billing_tax_added, Change-the-text-Story_87_-90_92_93 — descriptive

There is no enforced naming convention based on what's in the repo. Pick a style and be consistent within your feature. Verify with the team for the team's preferred convention.

Commit messages

Recent commits follow Conventional Commits loosely:

  • fix: update organization profile data assignment to use extracted_data for consistency
  • feat: improve Meta account reconnection logic by checking linked accounts before proceeding
  • refactor: replace all instances of 'content.Id' with 'contentId' for consistency and improved readability
  • Merge branch 'main' into uat_app

The patterns observed:

  • feat: — new feature
  • fix: — bug fix
  • refactor: — non-functional code change
  • chore: — build/tooling
  • Merge commits left as Git default

For new commits, follow the same style. The body of a commit message is rare in observed history — most messages are single-line.

Pull requests

The repo has a PR template at pull_request_template.md:

## Describe your changes

## Checklist before requesting a review

- [ ] I have performed a self-review of my code using [document link]

The template is minimal. Verify with the team what [document link] should point to (likely a self-review checklist held elsewhere).

When opening a PR:

  1. Target branch. Most feature work goes into dev_app. Promotion to uat_app and main is typically done via merge by a team lead — don't open feature PRs against main directly unless explicitly told to.
  2. Title. Match the commit-message style (feat: ..., fix: ...).
  3. Description. Fill in "Describe your changes" with the why and a one-sentence what. Don't paraphrase the diff line-by-line.
  4. Self-review. Tick the checkbox once you've actually re-read your own diff.
  5. Linked issues. No standard format observed in the codebase. Verify with the team.
  6. Screenshots / video. For UI changes, attach a screenshot or short Loom — the team relies on visual review since there's no automated UI testing.

What gets reviewed

Without a strict review process documented in the repo, here's what reviewers in this codebase tend to flag (inferred from commit history and code style):

  • Component name collisions. The Jenkins build greps for "Two component files resolving to the same name" and exits with code 100. Run a sanity check before pushing.
  • yarn.lock updates. Dependency changes must include the lockfile update. Don't manually edit yarn.lock.
  • Direct $axios calls for endpoints that are already cached in store/api.js. Prefer the cached actions.
  • Missing cache invalidation after a mutation (see 05-state-management.md).
  • Console logs and // CLEAN markers left in production code.
  • Polotno bundle changes without a rebuild. If you edited polotno-editor/, rebuild the bundle before pushing — otherwise CI will pass but the app won't reflect your changes.

What is not reviewed (but probably should be)

There is no automated test suite in this repo. There is no lint script in package.json. ESLint configuration exists but isn't wired to a script. SonarQube/SonarCloud appears to run on CI (there's a sonar-project.properties) but the gate isn't documented.

Consequences for review:

  • Reviewers can't rely on green CI to mean "the code works." Test changes in a browser before requesting review.
  • Style is enforced by prettier --write (yarn format). Run it before committing if you've touched pages/, components/, layouts/, or helpers/.
  • Type errors are not caught — there's no TypeScript and no vue-tsc step.

Common failure modes

The Jenkins pipeline prints warnings as exit code 100 (see 07-build-and-deploy.md). The following classes of warning will not fail the build but should block your PR:

  • Module not found / Cannot resolve.
  • Component-name collision.
  • Icon/asset 404 at build time.

Treat exit-code-100 deploys as PR cleanup, not "good enough."

Things to never do

These are not necessarily formalised but are reasonable inferences from the codebase:

  • Don't commit .env files. Lock them out via .gitignore (verify the project's .gitignore covers them) and git status before push.
  • Don't push directly to main, uat_app, or dev_app unless you're explicitly doing a merge or hotfix as designated by a team lead.
  • Don't rebase shared branches. This repo uses merge commits liberally. If you find yourself rebasing dev_app, you've gone off-track.
  • Don't rename component files for stylistic reasons. Many component imports are written by hand in component templates and renaming breaks them silently.
  • Don't remove "duplicate" CDN script tags in nuxt.config.js → head. They're often intentional (see 09-conventions.md).
  • Don't switch to npm. Yarn 1 (classic) is the project manager.
  • Don't add TypeScript. The codebase is JS-only — partial TypeScript adoption is a project-scale decision and shouldn't be smuggled in via individual PRs.

Code style

prettier is the only enforced formatter:

yarn format

That formats pages/**/*.vue, components/**/*.vue, layouts/**/*.vue, and helpers/**/*.js.

For everything else (style guide, mixin patterns, naming), see 09-conventions.md.

Documentation expectations

This is the part most often skipped. When you change one of the load-bearing files, update the corresponding doc in the same PR:

If you change… Update…
middleware/redirect.js 03-auth-and-sessions.md
middleware/axios.js 03-auth-and-sessions.md, 02-architecture.md
middleware/appendUrl.js 04-routing.md
store/api.js 05-state-management.md, 14-api-catalog.md
nuxt.config.js 02-architecture.md, 08-integrations.md
Dockerfile or Jenkinsfile 07-build-and-deploy.md
helpers/helper.js 17-helpers.md
Polotno bundle / editor pages 06-polotno-integration.md
New backend endpoint 14-api-catalog.md
New role / permission 12-permissions-and-roles.md
New domain term 11-glossary.md
New feature surface 19-feature-inventory.md

PRs that change these files without updating their docs should be sent back for the doc update — even if the code change is otherwise fine.

Releasing

The deploy process is automated by Jenkins (see 07-build-and-deploy.md). For the team's release cadence and approval process — verify with the team. Common questions a new contributor should ask early:

  • Who can promote dev_app → uat_app → main?
  • Is there a release window or freeze?
  • How are hotfixes handled (cherry-pick to main?)?
  • Where does the team announce a deploy (Slack, Teams)?

Asking for review

Open the PR, paste the link in the team's review channel (or wherever the team coordinates), and tag the relevant reviewer(s). For UI changes, drop a screenshot or short video in the PR. For backend-shape changes (new endpoints, payload shape changes), loop in the backend team — the frontend talks to a backend repo, and the contracts are not formally tracked here.

Sharp edges

  • Branches multiply faster than they're cleaned up. git branch -a shows dozens of stale feature branches. Don't be surprised; just delete your own when you're done.
  • Merge conflicts in yarn.lock are common when several feature branches add deps. Resolve by re-running yarn install rather than hand-editing.
  • Auto-deploy from dev_app. Pushing to dev_app triggers a Jenkins deploy — your code is live on the dev server within minutes. If you're not sure your change is ready, hold it on a feature branch instead.