Contributing Guide

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

Quick Start

# 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:

# 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:

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

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

Formatting

# Format code before committing
cargo fmt

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

Linting

# 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

# 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:

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

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

Verify Candid compatibility:

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

## 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:

1. PR approved and merged
2. GitHub Actions builds WASM
3. Deploys to staging canister
4. Posts deployment summary

Production (Manual)

Comment /deploy production on merged PR:

1. Requires write access
2. GitHub Actions validates permissions
3. Deploys to production canister
4. 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

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

Password Security

Use Argon2id for password hashing:

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:

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:

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

"Target wasm32-unknown-unknown not found"

Add the WASM target:

rustup target add wasm32-unknown-unknown

"Deployment failed: unauthorized"

Verify:

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

Tests timeout

For PocketIC tests, ensure WASM is built:

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

Resources

Internal Documentation

• Architecture Overview
• API Reference

External Resources

• Internet Computer Docs
• Rust Book
• Candid Reference
• ICRC Standards

Getting Help

• GitHub Issues: Bug reports, feature requests
• Pull Request Comments: Code review discussion
• Story Files: Check docs/sprints/stories/ for acceptance criteria

Welcome to the team!