Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
213 lines (164 loc) · 6.64 KB

CONTRIBUTING.md

File metadata and controls

213 lines (164 loc) · 6.64 KB
Raw

Contributing to NotifyChain

Thank you for your interest in contributing to NotifyChain! This document provides guidelines and instructions for contributing to the project.

Start here instead (recommended): CONTRIBUTOR_DEVELOPMENT_WORKFLOW_GUIDE.md

Code of Conduct

  • Be respectful and inclusive
  • Provide constructive feedback
  • Focus on what is best for the community
  • Show empathy towards other contributors

Getting Started

Prerequisites

To contribute to NotifyChain, make sure you have:

  • Rust installed with WebAssembly target (rustup target add wasm32-unknown-unknown)
  • Stellar CLI installed
  • Node.js (for listener and dashboard components)
  • Basic understanding of Soroban smart contracts, Git, and GitHub

Setup (Fork Workflow)

To set up a local development environment, follow this fork-and-clone workflow:

  1. Fork the Repository: Visit Notify-Chain and click the Fork button to create a copy of the repository under your GitHub account.
  2. Clone your Fork: 
    git clone https://github.com/your-username/Notify-Chain.git
cd Notify-Chain
  3. Configure Upstream Remote: Keep your fork updated by pointing to the upstream repository: 
    git remote add upstream https://github.com/Core-Foundry/Notify-Chain.git
  4. Verify Remotes: Run git remote -v to ensure your configuration is correct: 
    origin    https://github.com/your-username/Notify-Chain.git (fetch)
origin    https://github.com/your-username/Notify-Chain.git (push)
upstream  https://github.com/Core-Foundry/Notify-Chain.git (fetch)
upstream  https://github.com/Core-Foundry/Notify-Chain.git (push)

Syncing Your Fork

Before starting any new work or creating a branch, always pull the latest changes from the upstream main branch to prevent merge conflicts:

git checkout main
git fetch upstream
git merge upstream/main
git push origin main

Issue Claiming Process

To ensure that efforts are not duplicated and contributors can work on tasks they are interested in, we use the following issue claiming process:

  1. Browse Open Issues: Explore the GitHub Issue Tracker to find tasks. Look for issues labeled good first issue if you are new to the codebase.
  2. Claim an Issue:
    • Comment on the issue stating: I would like to work on this issue.
    • Wait for a maintainer to assign the issue to you. Once assigned, your username will appear under "Assignees" on GitHub.
    • Do not begin working on an issue or open a Pull Request for it unless it has been formally assigned to you. This prevents two developers from working on the same problem.
  3. Active Work & SLA:
    • Once assigned, you are expected to submit a draft PR or progress update within 5 days.
    • If there is no activity or communication on the issue after 5 days, the issue may be unassigned and made available for other contributors.
    • If you need more time, simply post an update on the issue so the maintainers know you are still active.

Development Workflow

1. Create a Branch

Always start from an up‑to‑date main:

git checkout main
git pull upstream main
git checkout -b <branch-name>

Use descriptive branch names following these conventions:

  • feature/ for new features
  • fix/ for bug fixes
  • docs/ for documentation
  • refactor/ for code refactoring
  • test/ for adding or modifying tests
  • chore/ for maintenance tasks

Example:

  • feature/add-slack-notifications
  • fix/resolve-event-deduplication-bug
  • docs/update-contributing-guide

2. Make Your Changes

  • Write clean, readable code
  • Follow existing code style in each directory
  • Add comments for complex logic
  • Update documentation as needed

3. Write and Run Tests

All new features and bug fixes must include tests.

Contract Tests (Rust)

cd contract/contracts/hello-world
cargo test

Listener Tests (TypeScript)

cd listener
npm install
npm test

Dashboard Tests (TypeScript)

cd dashboard
npm install
npm test

4. Commit Changes

Write clear, descriptive commit messages following Conventional Commits:

  • feat: new feature
  • fix: bug fix
  • docs: documentation changes
  • test: test additions or changes
  • refactor: code refactoring
  • chore: maintenance tasks

Example:

git commit -m "feat: add retry queue for failed notifications"
git commit -m "fix: resolve event parsing issue in listener"
git commit -m "docs: update README with setup instructions"

5. Push and Create PR

git push -u origin <branch-name>

Then create a Pull Request on GitHub!

Pull Request Guidelines

PR Title

Use the same format as commit messages:

  • feat: add retry queue for notifications
  • fix: standardize error messages across contracts

PR Description

Include:

  1. Overview: What changes does this PR introduce?
  2. Related Issue: Link to GitHub issue(s) this PR addresses
  3. Changes: What was added/removed/modified
  4. Verification Results: What tests passed, coverage, etc.
  5. How to Test: Instructions for testing your changes

PR Checklist

  • Code follows project style guidelines
  • Tests added/updated and passing
  • Documentation updated
  • All tests pass locally
  • Branch is up to date with main

Code Style Guidelines

Rust (Soroban Contracts)

Follow existing patterns in contract/contracts/hello-world/:

  • Format with cargo fmt
  • Add /// documentation comments for public functions/structs
  • Use #[contracterror] for custom errors
  • Test all functionality

TypeScript (Listener/Dashboard)

Follow the existing style in listener/ and dashboard/:

  • Run npm run lint before committing
  • Use TypeScript for type safety
  • Write unit tests for all new logic
  • Follow existing naming conventions

Review Process

For Contributors

  1. Ensure all tests pass locally
  2. Address reviewer feedback promptly
  3. Keep PR scope focused on a single issue or feature
  4. Be open to suggestions

For Reviewers

  1. Review code thoroughly
  2. Test locally if needed
  3. Provide constructive feedback
  4. Approve when ready

Questions?

  • Open an issue for bugs or feature requests
  • Check existing issues and PRs first
  • Join discussions on GitHub

License

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

Thank you for contributing to NotifyChain! 🎉