Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
257 lines (180 loc) · 7.49 KB

CONTRIBUTING.md

File metadata and controls

257 lines (180 loc) · 7.49 KB
Raw

Contributing to NotifyChain

Welcome, and thanks for your interest in contributing. This document is your starting point — it covers the contribution workflow, coding standards, and PR guidelines. Deeper references are linked throughout.

Documentation Map

Document Purpose
This file Workflow, standards, PR guidelines
CONTRIBUTOR_SETUP.md Full local environment setup from scratch
CONTRIBUTOR_DEVELOPMENT_WORKFLOW_GUIDE.md End-to-end workflow reference
CONTRIBUTOR_ARCHITECTURE_DEEP_DIVE.md System architecture and component internals
ARCHITECTURE_OVERVIEW.md High-level architecture walkthrough

Companion guides:

Code of Conduct

  • Be respectful and inclusive
  • Give constructive, specific feedback
  • Show empathy — everyone is learning

Prerequisites

Before you start, make sure you have:

  • Rust (stable) + WebAssembly target: rustup target add wasm32-unknown-unknown
  • Stellar CLI: cargo install --locked stellar-cli --features opt
  • Node.js 22 (used by both listener and dashboard in CI)
  • Git

For a detailed walkthrough including platform-specific notes, see CONTRIBUTOR_SETUP.md.

Quick Setup

With Docker (easiest)

Requires Docker Desktop (or Docker Engine + Compose on Linux). No Node.js install needed.

git clone https://github.com/YOUR-USERNAME/Notify-Chain.git
cd Notify-Chain
git remote add upstream https://github.com/Core-Foundry/Notify-Chain.git

cp .env.example .env
# Edit .env — set CONTRACT_ADDRESSES to your deployed contract ID

docker compose up --build

Dashboard → http://localhost:5173 · Listener API → http://localhost:8787

Without Docker

git clone https://github.com/YOUR-USERNAME/Notify-Chain.git
cd Notify-Chain
git remote add upstream https://github.com/Core-Foundry/Notify-Chain.git

cd listener && npm install && cp .env.example .env && npm run migrate
cd ../dashboard && npm install && cp .env.example .env

Minimum listener/.env:

STELLAR_RPC_URL=https://soroban-testnet.stellar.org:443
CONTRACT_ADDRESSES=[{"address":"YOUR_CONTRACT_ID","events":["*"]}]

Full setup details: CONTRIBUTOR_SETUP.md

Issue Claiming

  1. Browse open issues. New? Look for good first issue.
  2. Comment: I would like to work on this issue.
  3. Wait to be assigned — don't open a PR for unassigned work.
  4. Once assigned, submit a draft PR or progress update within 5 days. Post an update if you need more time.

Development Workflow

1. Sync and branch

Always start from an up-to-date main:

git checkout main
git fetch upstream
git merge upstream/main
git push origin main
git checkout -b <branch-name>

Branch naming:

Prefix Use
feature/ New features
fix/ Bug fixes
docs/ Documentation
refactor/ Refactoring
test/ Tests only
chore/ Maintenance

For the complete branching strategy — including naming rules, what to avoid, and how to recover from common mistakes — see docs/GIT_WORKFLOW.md.

2. Make Your Changes

2. Make changes

  • Follow the existing code style in each component directory.
  • Add comments for non-obvious logic.
  • Update docs when behavior changes.
  • Write tests for all new logic and bug fixes. Making a significant architectural change? Read the Architecture Decision Records first — they document why the current design is what it is. If your change alters one of those decisions, add a new ADR using docs/adr/0000-template.md and reference it in your PR.

Hit a problem? Check docs/CONTRIBUTOR_TROUBLESHOOTING.md before opening an issue.

3. Write and Run Tests

3. Run tests before pushing

Contracts (Rust)

cd contract
cargo fmt --all                              # format
cargo fmt --all -- --check                  # verify clean
cd contracts/hello-world && cargo test      # unit tests

Listener (TypeScript)

cd listener
npm run lint
npm run typecheck
npm test

Dashboard (TypeScript)

cd dashboard
npm run lint
npm run build    # includes TypeScript check
npm test

4. Commit

Follow Conventional Commits:

feat:     new feature
fix:      bug fix
docs:     documentation only
test:     tests only
refactor: no behavior change
chore:    maintenance

Examples:

git commit -m "feat: add retry queue for failed notifications"
git commit -m "fix: resolve event parsing issue in listener"
git commit -m "test: add payload validation edge cases"

5. Push and open a PR

git push -u origin <branch-name>

Then open a PR on GitHub against main. GitHub will pre-fill the PR template — fill it out completely.

Coding Standards

Rust (contracts)

  • Format with cargo fmt --all before every commit
  • Add /// doc comments on all public functions and structs
  • Use #[contracterror] for custom errors
  • Every public function needs a test

TypeScript (listener + dashboard)

  • npm run lint must pass with zero warnings
  • Use TypeScript — no any unless genuinely unavoidable
  • Unit test all new service logic
  • Follow existing file and naming conventions in the directory you're editing

Pull Request Guidelines

Title

Match commit convention: feat: add slack notification channel

Description

The PR template will prompt you for:

  1. Overview of what changed and why
  2. Linked issue number
  3. Key files modified
  4. Verification commands you ran
  5. Manual test instructions

Before submitting

  • Branch is up to date with main
  • All tests pass locally
  • Lint/format checks pass
  • Docs updated if behavior changed
  • PR scope is focused on a single issue

Review process

  • CI runs automatically — wait for green before requesting review.
  • Address feedback promptly and push to the same branch (the PR updates automatically).
  • Keep the scope tight — don't mix unrelated changes in one PR.
  • Reviewers will test locally for significant changes.

Automated Dependency Updates

Dependabot opens PRs weekly (Mondays) for outdated dependencies across all four ecosystems. Config is in .github/dependabot.yml.

When reviewing Dependabot PRs: check the changelog for breaking changes, wait for CI to pass, and review the migration guide for major version bumps.

Questions

  • Search existing issues first.
  • Open a new issue for bugs or feature requests.
  • Join discussions on GitHub.

By contributing, you agree your work will be licensed under the MIT License.