Skip to content

docs: add contributing guide for Soroban smart contracts - #192

Merged
snowrugar-beep merged 1 commit into
VertexChainLabs:mainfrom
BigJohn-dev:Define-a-CONTRIBUTING.md-for-the-smart-contract-workflow
Jul 17, 2026
Merged

docs: add contributing guide for Soroban smart contracts#192
snowrugar-beep merged 1 commit into
VertexChainLabs:mainfrom
BigJohn-dev:Define-a-CONTRIBUTING.md-for-the-smart-contract-workflow

Conversation

@BigJohn-dev

Copy link
Copy Markdown
Contributor

Closes #185

Description

Adds contracts/CONTRIBUTING.md with Soroban-specific guidance that the root CONTRIBUTING.md doesn't cover.

Problem: Root CONTRIBUTING.md only references generic Conventional Commits — no guidance on how to add a new entry point, when to bump an error enum, where to add tests, or how to handle storage migrations.

Solution: A dedicated contracts/CONTRIBUTING.md covering the full smart-contract workflow for Stellar/Soroban contributors.

Changes

Section What it covers
Adding a New Entry Point Step-by-step checklist (Design → Implement → Test → Submit)
Adding a New Contract Directory creation, Cargo.toml template, workspace registration in Cargo.toml
Error Enum Discipline #[repr(u32)] sequential discriminants (start at 1, never reorder/remove, always append), common variants table
Events Taxonomy Topic schema (domain / action / optional entity id), symbol_short! rules (≤9 chars), data payload conventions, stable topic requirement
Testing Inline #[cfg(test)] mod tests pattern, setup_test_env() helper, #[should_panic(expected = "Error(Contract, #N)")] conventions with discriminant comments, CI pipeline reference
Data-Model Migrations Full u128 → struct upgrade walkthrough: deploy new contract, write temp migrate entry point, run on testnet, remove after confirmation
Audit Checklist 30+ items across: correctness (auth, overflow checks), storage (DataKey discipline), events (every mutation emits), errors (full coverage with #[should_panic] tests), WASM build, deployment
Quick Reference Command table for all common operations

How to test

cd contracts
cargo test --workspace
Checklist
Documentation updated
Relevant issue linked
Changelog updated (N/A — docs-only change)

@snowrugar-beep snowrugar-beep left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@snowrugar-beep
snowrugar-beep merged commit a4ad563 into VertexChainLabs:main Jul 17, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Define a CONTRIBUTING.md for the smart-contract workflow

2 participants