Contributing Guide

Welcome to Hello World Co-Op DAO development! This guide covers the contribution workflow, code standards, and review process.

Quick Start

bash

# 1. Clone your target repository
cd ~/git
git clone <repo-url> <repo-name>

# 2. Create feature branch
cd <repo-name>
git checkout -b feature/your-feature-name

# 3. Make changes and test
cargo build --release --target wasm32-unknown-unknown
cargo test

# 4. Commit and push
git add .
git commit -m "feat: your descriptive message"
git push origin feature/your-feature-name

# 5. Create Pull Request on GitHub

Branch Naming Convention

Prefix	Purpose	Example
`feature/`	New features	`feature/kyc-verification`
`fix/`	Bug fixes	`fix/session-expiry`
`refactor/`	Code improvements	`refactor/auth-module`
`docs/`	Documentation	`docs/api-reference`
`test/`	Test additions	`test/governance-e2e`

Commit Message Format

Follow the Conventional Commits specification:

<type>: <short summary>

<optional body>

<optional footer>

Types:

Type	Description
`feat`	New feature
`fix`	Bug fix
`refactor`	Code refactoring (no behavior change)
`test`	Adding or improving tests
`docs`	Documentation updates
`chore`	Build scripts, dependencies
`style`	Formatting, whitespace
`perf`	Performance improvements

Examples:

bash

# Feature with scope
git commit -m "feat(auth): add multi-device session tracking"

# Bug fix
git commit -m "fix: prevent duplicate membership minting"

# With detailed body
git commit -m "refactor: extract session validation logic

- Move validation to separate module
- Add comprehensive error types
- Improve testability"

Code Standards

Rust

Compiler Settings

All canisters use strict warning enforcement:

toml

# .cargo/config.toml
[env]
RUSTFLAGS = "-D warnings"

All warnings are treated as errors. Code must compile cleanly.

Formatting

bash

# Format code before committing
cargo fmt

# CI will reject unformatted code
cargo fmt -- --check

Linting

bash

# Run Clippy with strict settings
cargo clippy --all-targets --all-features -- -D warnings

Fix all Clippy warnings. Common issues:

Unused imports → remove them
Unnecessary clone → use references
Complex match → use if-let

Naming Conventions

Element	Convention	Example
Functions	`snake_case`	`validate_session`
Types	`PascalCase`	`MembershipRecord`
Constants	`SCREAMING_SNAKE_CASE`	`MAX_DEVICES`
Modules	`snake_case`	`session_manager`

TypeScript/React

bash

# Check types
npx tsc --noEmit

# Run ESLint
npm run lint

# Format with Prettier
npm run format

Candid Interface Updates

When modifying public canister methods, update the .did file:

candid

// src/my_canister.did
service : {
  // Query methods
  "get_user": (principal) -> (opt UserRecord) query;

  // Update methods
  "create_account": (CreateAccountRequest) -> (variant { Ok: principal; Err: text });
}

Verify Candid compatibility:

bash

cargo build --release --target wasm32-unknown-unknown
ic-wasm target/wasm32-unknown-unknown/release/my_canister.wasm metadata candid:service

Pull Request Process

1. Before Creating PR

[ ] Code compiles without warnings
[ ] All tests pass (cargo test)
[ ] Code is formatted (cargo fmt)
[ ] Clippy passes (cargo clippy)
[ ] Candid interface updated (if public methods changed)
[ ] Documentation updated (if needed)

2. PR Description Template

markdown

## Summary
Brief description of what this PR does.

## Changes
- Added X functionality
- Fixed Y issue
- Refactored Z module

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing performed

## Related Issues
Fixes #123

3. Code Review

Reviewers look for:

Logic correctness
Security considerations
Test coverage
Code clarity
Performance implications

Responding to feedback:

Address all comments
Push additional commits (don't force-push)
Re-request review when ready

4. Merge Requirements

At least one approval
All CI checks pass
No merge conflicts
Branch up-to-date with main

Deployment Workflow

Staging (Automatic)

Merging to main triggers automatic deployment:

PR approved and merged
GitHub Actions builds WASM
Deploys to staging canister
Posts deployment summary

Production (Manual)

Comment /deploy production on merged PR:

Requires write access
GitHub Actions validates permissions
Deploys to production canister
Posts deployment confirmation

Never use dfx deploy manually. All deployments go through GitHub Actions.

Security Guidelines

Secrets Management

Never hardcode secrets, API keys, or private keys
Use GitHub Secrets for CI/CD
Use environment variables for local development

Input Validation

rust

// Always validate inputs
pub fn create_account(email: String) -> Result<Principal, String> {
    if !is_valid_email(&email) {
        return Err("Invalid email format".to_string());
    }
    // ...
}

Password Security

Use Argon2id for password hashing:

rust

use argon2::{Argon2, PasswordHasher};

fn hash_password(password: &str) -> String {
    let salt = SaltString::generate(&mut OsRng);
    let argon2 = Argon2::default();
    argon2.hash_password(password.as_bytes(), &salt)
        .unwrap()
        .to_string()
}

Security Event Logging

Use consistent markers for audit logging:

rust

ic_cdk::println!("🔐 Login attempt for user: {}", user_id);
ic_cdk::println!("🎟️ Session created: {}", session_id);
ic_cdk::println!("🚫 Access denied: {}", reason);
ic_cdk::println!("✅ Password reset completed for: {}", user_id);

Common Issues

"Failed to read WASM file"

Build the canister first:

bash

cargo build --release --target wasm32-unknown-unknown

"Target wasm32-unknown-unknown not found"

Add the WASM target:

bash

rustup target add wasm32-unknown-unknown

"Deployment failed: unauthorized"

Verify:

You have write access to the repository
GitHub secrets are configured
Your identity is a canister controller

Tests timeout

For PocketIC tests, ensure WASM is built:

bash

cargo clean
cargo build --release --target wasm32-unknown-unknown
cargo test

Contributing Guide

Quick Start

Branch Naming Convention

Commit Message Format

Code Standards

Rust

Compiler Settings

Formatting

Linting

Naming Conventions

TypeScript/React

Candid Interface Updates

Pull Request Process

1. Before Creating PR

2. PR Description Template

3. Code Review

4. Merge Requirements

Deployment Workflow

Staging (Automatic)

Production (Manual)

Security Guidelines

Secrets Management

Input Validation

Password Security

Security Event Logging

Common Issues

"Failed to read WASM file"

"Target wasm32-unknown-unknown not found"

"Deployment failed: unauthorized"

Tests timeout

Resources

Internal Documentation

External Resources

Getting Help

Contributing Guide ​

Quick Start ​

Branch Naming Convention ​

Commit Message Format ​

Code Standards ​

Rust ​

Compiler Settings ​

Formatting ​

Linting ​

Naming Conventions ​

TypeScript/React ​

Candid Interface Updates ​

Pull Request Process ​

1. Before Creating PR ​

2. PR Description Template ​

3. Code Review ​

4. Merge Requirements ​

Deployment Workflow ​

Staging (Automatic) ​

Production (Manual) ​

Security Guidelines ​

Secrets Management ​

Input Validation ​

Password Security ​

Security Event Logging ​

Common Issues ​

"Failed to read WASM file" ​

"Target wasm32-unknown-unknown not found" ​

"Deployment failed: unauthorized" ​

Tests timeout ​

Resources ​

Internal Documentation ​

External Resources ​

Getting Help ​

Contributing Guide

Quick Start

Branch Naming Convention

Commit Message Format

Code Standards

Rust

Compiler Settings

Formatting

Linting

Naming Conventions

TypeScript/React

Candid Interface Updates

Pull Request Process

1. Before Creating PR

2. PR Description Template

3. Code Review

4. Merge Requirements

Deployment Workflow

Staging (Automatic)

Production (Manual)

Security Guidelines

Secrets Management

Input Validation

Password Security

Security Event Logging

Common Issues

"Failed to read WASM file"

"Target wasm32-unknown-unknown not found"

"Deployment failed: unauthorized"

Tests timeout

Resources

Internal Documentation

External Resources

Getting Help