Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
85 lines (64 loc) · 4.17 KB

CONTRIBUTING.md

File metadata and controls

85 lines (64 loc) · 4.17 KB
Raw

This is a fantastic template. It is strict enough to keep the codebase secure, but clear enough that a new contributor knows exactly what is expected of them.

Since StellarYield is a full-stack application (Frontend, Backend, and Smart Contracts), I have adapted that exact "Access Layer" format to fit your specific repository.

Here is the polished Markdown. You can paste this directly into a CONTRIBUTING.md file in your root directory, or add it as a ## Contributing section at the bottom of your README.md.

## 🤝 Contributing to StellarYield

Thanks for contributing to StellarYield, a Stellar-native DeFi yield aggregator and automated vault system. We rely on the community to help build secure, efficient, and accessible DeFi tools.

### 🛑 Before You Start
* **Read the Docs:** Review the `README.md` for overall architecture context.
* **Claim an Issue:** Browse the active issues (especially those tagged for the Drips Wave) before starting work. Please ask to be assigned before opening a PR.
* **Keep it Focused:** Keep Pull Requests limited to one specific feature, bug fix, or contract concern at a time.
* **Discuss Major Changes:** Start a discussion in the issues tab before changing core architecture, smart contract storage models, or automated routing logic.

### 💻 Local Setup
Since StellarYield is a full-stack monorepo, ensure you have the correct environments set up for the stack you are touching:
* **Smart Contracts:** Install the stable Rust toolchain and the `soroban-cli`. Make sure `rustfmt` and `clippy` are available.
* **Frontend/Backend:** Ensure Node.js (v18+) is installed.

### ✅ Verification Commands
Before submitting a Pull Request, your code must pass the following local checks. PRs with failing checks will not be reviewed.

**For Smart Contracts (`/contracts`):**
```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

For Frontend & Backend (/client and /server):

npm run lint
npm run test

📜 Core Contribution Rules

  1. Security First: Treat vault deposits, withdrawals, fee structures, and rebalancing logic as high-sensitivity areas.
  2. Document State Changes: Document any smart contract storage or event changes clearly using NatSpec-style comments.
  3. Test Everything: Add or update unit tests for every behavior change. Minimum 90% coverage is expected for financial logic.
  4. Contextual Naming: Keep variable names and comments specific to StellarYield and Soroban, avoiding generic template wording.

🌟 Good First Issue Guidance

If you are adding a "Good First Issue" to the backlog, it should:

  • Avoid protocol-level economic or security changes.
  • Have a narrow scope (e.g., a single UI component or a read-only view function).
  • Include explicit acceptance criteria.
  • Be easily testable in isolation.

🧪 Running the Fuzzing Suite

The vault includes a property-based testing suite built with proptest. To run the fuzz tests:

cd contracts
cargo test --test fuzz_tests -- --nocapture

To run with more iterations (recommended before merging security-sensitive changes):

PROPTEST_CASES=100000 cargo test --test fuzz_tests -- --nocapture

The fuzzing suite validates the following invariants:

  • total_shares and total_assets are never negative
  • First depositor receives 1:1 shares
  • Full withdrawal returns the exact deposited amount for a sole depositor
  • Multi-user deposits produce proportional shares
  • Share price never decreases from deposit/withdraw operations
  • Rebalance correctly updates tracked assets

❓ Questions & Scope

If a change requires touching the client UX, the backend API, and the smart contracts, please split that work into separate, sequential Pull Requests to make reviewing easier and safer.


***

### 🏁 Next Step
Having this in your repo is going to save you so much time answering basic questions from Drips Wave contributors. 

**Would you like me to generate a `pull_request_template.md` file next?** When a contributor opens a PR, GitHub will automatically load the template, forcing them to check off boxes confirming they ran `cargo clippy` and linked the correct issue number!