Skip to main content

Contributing guide

This is the end-to-end contribution workflow for postman-app: how to structure your branch, write a good PR, get it reviewed, and understand what happens after merge.

Based on the App contribution guidelines and current team conventions.

Before you start​

Every piece of work in postman-app should have a Jira ticket before a single line of code is written. Before picking up an issue, confirm:

  • The Jira ticket has a clear title and description
  • There is a supporting document attached: an engineering spec for features, or a Root Cause Analysis (RCA) for bug fixes
  • The proposed solution has been reviewed and approved
  • Any previous context or prior attempts are documented on the ticket

This is not bureaucracy — it is how postman-app avoids the most common failure mode in large codebases: engineers building the wrong thing with confidence.

Branching​

Always branch from develop. The develop branch is the single source of truth — it ships to all channels (dev, beta, canary, stage) and eventually to production.

git checkout develop
git pull
git checkout -b feat/JIRA-ID-short-description
# Example: feat/CSDK-1234-workspace-activity-feed

Branch naming: feat/, fix/, refactor/, or chore/ followed by the Jira ID and a short description.

Production-ready from day one

Since develop is the branch that ships everywhere, any code merged to it must be production-ready. Do not submit high-risk changes close to a code freeze date. Changes to core flows — app launch, auth, base components — with insufficient test coverage are high-risk. Plan accordingly.

During development​

A few habits that save everyone time:

  • Keep your branch up to date. Pull from develop regularly — especially before creating the PR.
  • Commit the Jira ID. Every commit message should reference the ticket. Example: [CSDK-1234] feat: add activity feed container
  • Post daily updates on Jira — especially if you're blocked. Surface blockers early.

Writing good release notes​

Every PR must include release notes in the changedoc. Release notes are how changes are communicated to users — they are as important as the code itself.

Write about the user experience, not the implementation.

✅ Good❌ Bad
Fixed a bug where saving a collection with a long name caused the sidebar to freezeFixed a race condition in CollectionStore.save()
You can now drag environments between workspacesAdded drag-and-drop support to EnvironmentController
Improved app startup time by 30% on WindowsOptimized byte code caching for V8

Rules:

  • No internal or technical terminology
  • Describe what changed for the user, not what you changed in code
  • Add screenshots for UI changes
  • Add performance benchmarks if the change affects performance

Creating the PR​

Before requesting a review, go through this checklist. Every unchecked item is a predictable round-trip that delays your merge.

Contributor checklist:

□ Title is meaningful — describes the change, not the branch name
  Example: "Fix sidebar freeze when collection name exceeds 255 characters"
  Not: "CSDK-1234-fix-sidebar-bug"

□ Description includes:
  - What changed and why (link the Jira ticket)
  - Before/after screenshots for any UI changes
  - Any context the reviewer needs that isn't obvious from the diff

□ Self-reviewed the diff — you caught your own issues first

□ No debugging statements left in (console.log, debugger, commented-out code)

□ In-code documentation added where needed

□ Release notes are written and follow the guidelines above

□ Jira moved to "In Review" with a link to the PR

□ All CI checks are passing

Requesting a review​

Tag the right reviewers — people who have context on the area you changed. If you're unsure who to ask, look at recent contributors to the files you changed using git log.

The best PR review is one where both sides have clear expectations upfront. Tell the reviewer:

  • What you want them to focus on
  • What you deliberately did not change and why
  • Any known trade-offs

Reviewing a PR​

Reviewer checklist:

□ Title and description are clear and meaningful
□ Release notes are present and follow the writing guidelines
□ Target branch is correct (should be develop)
□ All CI checks pass
□ Necessary tests are added or updated
□ No scope creep — the change matches the Jira ticket
□ No deviations from the feature spec or RCA document

Review principles:

  • Do the full review in one pass — avoid multiple round-trips on the same issue
  • Don't focus on code style (lint handles that). Focus on correctness, architecture, and test coverage
  • Don't let the PR sit. A PR waiting for review is a blocked engineer
  • Don't expand scope during review — if you see something unrelated, open a new ticket

After merge: staging review​

When a release hits code freeze, it moves through stage channel deployments. During this window:

  • Keep the Jira ticket updated — move it to "In Stage"
  • Monitor any findings from security or quality review
  • Address findings promptly — do not block stable releases waiting for a perfect fix

After release​

When the change is in the stable production release:

  • Update the GitHub issue noting the release version
  • Close the GitHub issue
  • Mark the Jira ticket as Done

Hotfixes​

If a critical bug needs to go straight to production bypassing the normal release cycle:

  1. Create a Jira ticket to track the hotfix
  2. Branch from develop 
    git checkout -b fix/hotfix-JIRA-ID-short-title
  3. Write the RCA before touching code
  4. Create a PR — title format: [HOTFIX][JIRA-ID] description
  5. Coordinate with your team lead for expedited review and deployment

Reference​