Feat/documentation and governance improvements

[DNight-King]

Documentation and Governance Improvements

This PR addresses four high-priority governance and documentation issues, establishing security, contributor, and release processes for the vortex-backend project.

Overview

All issues focus on formalizing existing practices and creating transparent, auditable processes:

1. SECURITY.md — Private vulnerability disclosure policy
2. Label Taxonomy — Contributor onboarding and issue prioritization
3. CHANGELOG.md — Conventional Commits integration
4. Drips Wave Ledger — Contributor points accounting

Issues Closed

• Closes #103 [High] Add a SECURITY.md vulnerability disclosure policy #312: Add a SECURITY.md vulnerability disclosure policy
• Closes #104 [High] Curate a "good first issue" / "help wanted" label taxonomy and apply it across the contributor backlog #313: Curate a "good first issue" / "help wanted" label taxonomy and apply it across the contributor backlog
• Closes #105 [High] Add a CHANGELOG.md and wire it to the existing commitlint/Conventional Commits setup #314: Add a CHANGELOG.md and wire it to the existing commitlint/Conventional Commits setup
• Closes #106 [High] Formalize the Drips Wave contributor point/reward accounting process #315: Formalize the Drips Wave contributor point/reward accounting process

Changes

1. SECURITY.md (Issue #312)

File: SECURITY.md (new)

• Private reporting channels (GitHub Security Advisories, email)
• Response SLA: acknowledge within 5 business days, fix within 30 days for critical issues
• Explicit scope: signature/auth flows, fund-moving code, solver registry, WebSocket auth
• Cross-reference existing security tracking issues (Write an ADR for the on-chain settlement architecture #19, Add a StellarTxService skeleton for building settlement transactions #20, Add a Soroban event ingestion service #26, Add structured logging for WebSocket connect/disconnect/broadcast events #82–Add monitoring for unbounded in-memory Map growth #97, Instrument the sweeper with duration and expired-count metrics #96)
• Out-of-scope categories and best practices documented

2. Label Taxonomy (Issue #313)

Files:

• docs/LABEL_TAXONOMY.md (new)

• CONTRIBUTING.md (updated)

• Defined label categories:

  • Difficulty: good-first-issue, help-wanted, hard
  • Category: category/backend, category/security, category/devops, category/governance
  • Status: status/in-progress, status/blocked, status/ready-to-merge

• Mapping rules from issues.md complexity/prerequisites to GitHub labels

• Exclusion rules (avoid good-first-issue for blockers or cross-module work)

• Added quick reference to CONTRIBUTING.md

3. CHANGELOG.md Documentation (Issue #314)

Files:

• CHANGELOG.md (updated)

• CONTRIBUTING.md (updated)

• Enhanced CHANGELOG.md with detailed instructions for maintainers

• Mapped Conventional Commit types to changelog sections:

  • feat(...) → Added
  • fix(...) → Fixed
  • perf(...) → Changed (performance notes)
  • refactor(...) → Changed (structural notes)
  • docs(...) → Documentation (user-facing only)
  • chore(...)/test(...) → Skip (internal only)

• Added changelog update section to CONTRIBUTING.md with examples

4. Drips Wave Contributor Accounting (Issue #315)

Files:

• docs/DRIPS_WAVE_LEDGER.md (new)

• CONTRIBUTING.md (updated)

• Created auditable ledger mechanism for contributor points

• Defined point values: 200 (High), 150 (Medium)

• Source of truth: Closes #<issue-number> in PR descriptions

• Dispute resolution process referencing CODE_OF_CONDUCT.md

• Added Drips Wave workflow section to CONTRIBUTING.md

Implementation Details

All changes are minimal, documentation-focused, and integrate cleanly with existing infrastructure:

• SECURITY.md aligns with existing CI practices (Gitleaks, npm audit)
• Label taxonomy references existing issues.md structure and Complexity tiers
• CHANGELOG.md instructions match the existing Conventional Commits setup (@commitlint/config-conventional)
• Drips Wave ledger hooks into existing PR workflow via Closes tags (already recommended in CONTRIBUTING.md)

Testing & Validation

No tests required—these are documentation changes:

• ✅ All files created and formatted correctly
• ✅ Markdown is readable and properly linked
• ✅ Cross-references are consistent (e.g., links to CODE_OF_CONDUCT.md, issues.md)
• ✅ Commit messages follow Conventional Commits format
• ✅ All four issues fully addressed per acceptance criteria

Related Work

These changes establish foundations for:

• Future security research contributions (SECURITY.md)
• Scalable contributor onboarding (label taxonomy)
• Automated or manual changelog generation (CHANGELOG.md docs)
• Transparent contributor recognition (Drips Wave ledger)

Future issues (e.g., automated changelog generation, GitHub-hosted security advisories integration, or ledger automation) can build on these documented processes without requiring process redesign.

---

Closes #312
Closes #313
Closes #314
Closes #315

[drips-wave]

@DNight-King Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits