Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
356 lines (255 loc) · 10.2 KB

CONTRIBUTING.md

File metadata and controls

356 lines (255 loc) · 10.2 KB
Raw

Contributing to Navin Frontend

Hi There! We're super happy you want to contribute to the Navin frontend! Please read this carefully before you start — it saves everyone time. We only accept effective, well-structured contributions so our codebase stays healthy and maintainable.

Table of Contents

About the Project

Navin is a blockchain-powered logistics platform that improves supply chain visibility for enterprises through tokenized shipments, immutable milestone tracking, and automated settlements. By creating a zero-trust interface between logistics providers and their clients, Navin aims to ensure both parties access identical real-time data — removing information asymmetry and enabling seamless, dispute-free operations.

This repository is the frontend of the Navin platform — a React application that provides real-time dashboards for logistics companies and customers to track shipment status, visualize on-chain milestones, and monitor automated payment settlements.

Getting Started

Prerequisites

  • Node.js v18 or later
  • pnpm v10 or later (required package manager)

To install pnpm:

npm install -g pnpm
# or
curl -fsSL https://get.pnpm.io/install.sh | sh -

Fork & Clone

  1. Fork this repository on GitHub.

  2. Clone your fork locally:

    git clone https://github.com/YOUR-USERNAME/navin-frontend.git
cd navin-frontend

  3. (Optional) Add the upstream remote to sync future updates: You can sync through the github website though

    git remote add upstream https://github.com/Navin-xmr/navin-frontend.git

  4. Install dependencies:

    cd frontend
pnpm install

  5. Start the development server:

    pnpm run dev

Picking an Issue

All open tasks for this repository are listed in ISSUES.

Each issue has:

  • The points lets you know how complex it is:
  • A description of what needs to be built
  • Acceptance criteria — your PR should meet all of them before it will be merged

Start with an issue with like 100 points or 150 points if it's your first contribution.

Once you've decided on an issue, leave a comment and wait to be assigned before starting the work.

Making Contributions

Important

All PRs must target the dev branch, not main. The main branch is protected and only receives merges from dev after testing.

Step 1: Create a Branch

Never commit directly to your fork's main or dev. Always work on a dedicated feature branch. Sync your fork first (via GitHub website or by pulling upstream), then:

git checkout dev
git pull origin dev    # or: git pull upstream dev

git checkout -b issue#<number>

Examples:

issue#9
issue#24
issue#51

Step 2: Make Your Changes

  • Follow the existing code patterns and component structure in the project
  • Keep each branch/PR focused on one issue only — don't bundle unrelated changes
  • Add or update tests if the issue involves logic
  • Make sure the app builds and runs without errors before pushing

Step 3: Run Checks Locally

Before pushing, always run these:

# Check formatting
pnpm run lint

# Run any existing tests
pnpm run test

# Verify the build works
pnpm run build

Fix any errors or warnings before pushing.

Commit Guidelines

Write clear commit messages so the history tells a story.

Format

type: short description

Commit Types we prefer

Type When to use
feat New component or page
fix Bug fix
style Visual-only change (CSS, layout), no logic change
refactor Code restructuring with no functional change
test Adding or updating tests
docs Documentation changes
chore Config, dependencies, maintenance

Examples

git commit -m "feat: build shipment tracking timeline component"
git commit -m "fix: resolve mobile layout overflow on dashboard sidebar"
git commit -m "style: update status badge colors to match design system"
git commit -m "docs: add JSDoc comments to API service functions"

Pull Request Process

Step 1: Push Your Branch

git push origin issue#<number>

Step 2: Open a Pull Request

Important

Ensure your PR targets the dev branch, not main. GitHub will show the target branch in the PR creation interface.

  1. Go to your fork on GitHub and click "Compare & pull request"
  2. Verify the base branch is set to dev (not main)
  3. Fill out the PR description:
    • Title: What you built (e.g., feat: build notification dropdown)
    • Issue: Reference the issue (e.g., Closes #43)
    • Description: Brief summary of your approach
    • Testing: How you verified it works — list what you tested
    • Screenshots: Required for all frontend PRs — attach a screenshot or screen recording of the UI you built. PRs without visuals will not be reviewed.
    • Design file (design issues only): Link to your design document in docs/designs/.

Review Process

  1. CI checks run automatically on every push (lint + build must pass)
  2. Maintainer review typically within 1–2 days
  3. Address feedback — push fixes to the same branch of your PR
  4. Once approved and CI passes, a maintainer will merge your PR

Resolving Conflicts

Conflicts happen when other PRs are merged while you're working on your branch. Here's how to fix them: (This is just one way to do it, you can use the website to update your fork if that is the method you prefer)

# Update your local dev
git checkout dev
git pull upstream dev    # or: git pull origin dev

# Rebase your branch on top of updated dev
git checkout issue#<number>
git rebase dev

Important

Do not blindly accept both sides of a conflict. Read each conflict carefully, understand what changed on both sides, pick the correct resolution (or merge intentionally), then verify the build and tests still pass before pushing.

After resolving:

npm run lint
npm run build

git push origin issue#<number>

You can also push your fix of the conflicts this way if you did the rebase method

# Push (force-with-lease is safe after a rebase)
git push origin issue#<number> --force-with-lease

PRs with unresolved or carelessly merged conflicts will not be merged. We can't have any PR lead to issues on our repository so other contributors do not complain. We want contributors focused on building, not cleaning up others' mistakes please.

Code Standards

General

  • Write clean, readable code — favor clarity over cleverness
  • Use consistent naming: PascalCase for components, camelCase for variables and functions
  • Keep components small and focused — one responsibility per component
  • Use Tailwind CSS utility classes for styling (see Tailwind guidelines below)

Tailwind CSS Guidelines

We use Tailwind CSS for all styling. Follow these best practices:

Use Design Tokens

Always use our custom design tokens from tailwind.config.js:

// Good: Using design tokens
className="bg-background-card text-primary border-border"

// Bad: Hardcoded colors
className="bg-[#0F1419] text-[#00D9FF] border-[#1E2433]"

Keep Utilities Readable

If a component has more than 10 utility classes, consider:

  1. Breaking it into smaller components
  2. Creating a reusable component with variants
  3. Grouping related utilities logically
// Good: Grouped logically
className="
  flex items-center justify-between gap-4
  px-6 py-3 rounded-2xl
  bg-background-card border border-border
  hover:border-accent-blue transition-all duration-300
"

// Bad: Random order
className="px-6 hover:border-accent-blue flex bg-background-card py-3 items-center"

Create Reusable Components

For repeated patterns, create reusable components:

// Good: Reusable Button component
<Button variant="primary" size="lg">Click Me</Button>

// Bad: Repeating utilities everywhere
<button className="px-8 py-3.5 bg-accent-blue text-white rounded-full...">

Mobile-First Responsive Design

Tailwind uses mobile-first breakpoints:

// Good: Mobile-first
className="flex-col md:flex-row p-4 md:p-8"

// Bad: Desktop-first
className="flex-row md:flex-col p-8 md:p-4"

When to Use CSS Files

Only create separate CSS files for:

  • Complex animations with @keyframes
  • Third-party library overrides
  • Very complex pseudo-elements that are hard to read inline

For everything else, use Tailwind utilities.

Migration Reference

See docs/TAILWIND_MIGRATION.md for:

  • Complete migration patterns
  • Common component examples
  • Troubleshooting guide
  • Design token reference

Component Structure

src/
├── components/         # Reusable shared components
├── pages/              # Page-level components (one per route)
├── services/           # API service functions
├── hooks/              # Custom React hooks
├── context/            # React context providers

PR Size

Keep PRs focused. A PR for a single issue should not touch unrelated files.

Getting Help

  • Issues & Tasks: See ISSUES for all open work
  • Security: Email navinxmr@gmail.com — do not open a public issue for vulnerabilities right now
  • Community: Join our Telegram group and ask directly for assistance if necessary — Navin Community Chat

Thank you for contributing to Navin Frontend! Together, we're building a transparent and secure logistics platform on Stellar.