From 29cdd93a8d36f53a42ce06a29b774eb036ec3c92 Mon Sep 17 00:00:00 2001 From: Isaac Ochuko Date: Mon, 31 Aug 2026 09:22:11 +0000 Subject: [PATCH 1/4] docs: add contributor workflow and setup guide --- CONTRIBUTING.md | 57 ++++++++++++++++++++++++++++++++++++------------- README.md | 6 ++++-- 2 files changed, 46 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 80b6391..b915336 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,53 @@ # Contributing to vortex-backend > This document covers **backend-specific** setup and conventions. -> For the process, code of conduct, and org-wide guidelines, see the -> [org-wide CONTRIBUTING.md](https://github.com/vortex-protocol/.github/blob/main/CONTRIBUTING.md). - -Closes #135 +> For the repository's community expectations and RFC workflow, see +> [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) and +> [docs/rfcs/README.md](./docs/rfcs/README.md). --- ## Table of contents -1. [Prerequisites](#prerequisites) -2. [Getting started](#getting-started) -3. [Development workflow](#development-workflow) -4. [Running the test suite](#running-the-test-suite) -5. [Code conventions](#code-conventions) -6. [Module and file structure](#module-and-file-structure) -7. [Adding a new endpoint](#adding-a-new-endpoint) -8. [Environment variables](#environment-variables) -9. [Regenerating the API client SDK](#regenerating-the-api-client-sdk) -10. [Commit messages](#commit-messages) -11. [Submitting a pull request](#submitting-a-pull-request) +1. [Contributor workflow](#contributor-workflow) +2. [Prerequisites](#prerequisites) +3. [Getting started](#getting-started) +4. [Development workflow](#development-workflow) +5. [Running the test suite](#running-the-test-suite) +6. [Code conventions](#code-conventions) +7. [Module and file structure](#module-and-file-structure) +8. [Adding a new endpoint](#adding-a-new-endpoint) +9. [Environment variables](#environment-variables) +10. [Regenerating the API client SDK](#regenerating-the-api-client-sdk) +11. [Commit messages](#commit-messages) +12. [Submitting a pull request](#submitting-a-pull-request) + +--- + +## Contributor workflow + +Before opening a PR, pick a task from the GitHub issue tracker and keep the work scoped to that issue. The preferred workflow is: + +1. Create a small feature branch from `main`. +2. Keep the implementation focused on the issue at hand. +3. Validate the affected commands locally (`npm run lint`, `npm run typecheck`, and the relevant test targets). +4. Open a PR with a clear summary and a link to the issue. + +Commit messages follow Conventional Commits and are enforced by the `commitlint` job in [`.github/workflows/ci.yml`](./.github/workflows/ci.yml). The typical format is: + +```bash +(): +``` + +Examples: + +```bash +docs: add contributor onboarding +fix: validate soroban config in production +feat: add quote endpoint cache +``` + +If your change affects the protocol contract, persisted schema, or WebSocket semantics, start by reading [docs/rfcs/README.md](./docs/rfcs/README.md) and open an RFC before implementation. --- diff --git a/README.md b/README.md index 7c2a868..1c492dc 100644 --- a/README.md +++ b/README.md @@ -185,8 +185,10 @@ versus **planned** (schema/token data in place, on-chain settlement pending). ## Contributing -See [CONTRIBUTING.md](./CONTRIBUTING.md) for backend-specific setup, conventions, and -the PR checklist. It links to the org-wide guide for process and code of conduct. +See [CONTRIBUTING.md](./CONTRIBUTING.md) for backend-specific setup, conventions, +and the PR checklist. For community expectations and governance, see +[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) and +[docs/rfcs/README.md](./docs/rfcs/README.md). ## License From a196843447aad575e63d5bf9c4df2e2b73e22998 Mon Sep 17 00:00:00 2001 From: Isaac Ochuko Date: Mon, 31 Aug 2026 09:22:27 +0000 Subject: [PATCH 2/4] docs: add community code of conduct --- CODE_OF_CONDUCT.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..41f6315 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,55 @@ +# Contributor Covenant Code of Conduct + +## Our pledge + +We as members, contributors, and maintainers pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Scope + +This Code of Conduct applies to all project spaces, including GitHub issues, pull requests, code review, and any other communication or event hosted by the project or its maintainers. + +## Standards + +Examples of behavior that contributes to a positive environment include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing viewpoints and experiences +- Giving and gracefully accepting constructive feedback +- Taking responsibility for mistakes and learning from them +- Focusing on what is best for the community and the project + +Examples of unacceptable behavior include: + +- Harassment, intimidation, or discrimination of any kind +- Trolling, baiting, or deliberate disruption of discussions +- Personal attacks or insulting comments +- Publishing private information without explicit permission +- Any behavior that threatens the safety or participation of others + +## Enforcement responsibilities + +Project maintainers are responsible for clarifying and enforcing this Code of Conduct. When a report is made, maintainers will review the situation, consider the context, and take appropriate action to maintain a safe and respectful project environment. + +## Reporting + +If you experience or witness unacceptable behavior, report it as early as possible. For routine concerns, use the repository's public issue or pull request discussion to request a private follow-up with the maintainers. For sensitive or urgent issues, contact the repository maintainers through the project admin channel and request a confidential report. + +We aim to acknowledge reports within 48 hours and provide a next-step update within 5 business days, depending on the complexity of the report. + +## Enforcement ladder + +The maintainers may apply the following steps, in order, when behavior violates this Code of Conduct: + +1. Warning: a private reminder that the behavior is not acceptable. +2. Temporary restriction: limits on participation in discussions, pull requests, or project spaces for a defined period. +3. Permanent removal: an indefinite ban from the project when a pattern of behavior continues or the offense is severe. + +The repository maintainers have the authority to enact these actions and to escalate the matter to the broader project owner or organization as needed. + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. From 757aceffd1749fa12143850da3f0faa834a4dc41 Mon Sep 17 00:00:00 2001 From: Isaac Ochuko Date: Mon, 31 Aug 2026 09:22:41 +0000 Subject: [PATCH 3/4] chore: add CODEOWNERS review routing --- CODEOWNERS | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 CODEOWNERS diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..624ed76 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,19 @@ +# CODEOWNERS +# Keep the most specific rules above broad fallback rules. GitHub uses the +# last matching rule, so the general ownership rule is intentionally placed at +# the end of the file. + +# Core protocol and platform areas +/src/soroban/ @vortex-protocol/soroban +/src/intents/ @vortex-protocol/intents +/src/solvers/ @vortex-protocol/solvers +/src/routing/ @vortex-protocol/routing +/src/tokens/ @vortex-protocol/tokens +/src/common/ @vortex-protocol/platform +/src/config/ @vortex-protocol/platform +/src/stats/ @vortex-protocol/stats +/prisma/ @vortex-protocol/data-models +/.github/workflows/ @vortex-protocol/platform +/docs/ @vortex-protocol/docs + +* @vortex-protocol/maintainers From bfb83b69ac8977ffeaa5c0058d0f59d7be864004 Mon Sep 17 00:00:00 2001 From: Isaac Ochuko Date: Mon, 31 Aug 2026 09:22:59 +0000 Subject: [PATCH 4/4] docs: add RFC process for protocol changes --- docs/rfcs/0000-template.md | 25 +++++++++++++++++++++++++ docs/rfcs/README.md | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 docs/rfcs/0000-template.md create mode 100644 docs/rfcs/README.md diff --git a/docs/rfcs/0000-template.md b/docs/rfcs/0000-template.md new file mode 100644 index 0000000..e542fb1 --- /dev/null +++ b/docs/rfcs/0000-template.md @@ -0,0 +1,25 @@ +# RFC: + +## Summary + +Describe the proposed change in 1-3 paragraphs. + +## Motivation + +Why is this change needed? What problem does it solve? + +## Proposed change + +Explain the design, affected files, and how the change behaves. + +## Alternatives considered + +Briefly describe other options and why they were rejected. + +## Backward-compatibility impact + +State whether the proposal changes persisted data, the WebSocket protocol, or on-chain semantics. Call out migration or rollout concerns. + +## Related work + +List the relevant issue, PR, or subsystem owners. diff --git a/docs/rfcs/README.md b/docs/rfcs/README.md new file mode 100644 index 0000000..2576146 --- /dev/null +++ b/docs/rfcs/README.md @@ -0,0 +1,36 @@ +# RFC process + +This repository uses a lightweight RFC process for design changes that affect the protocol, public API, persistence model, or contract semantics. The goal is to get early feedback before a large or protocol-sensitive change becomes expensive to unwind. + +## When an RFC is required + +Open an RFC before implementing a change that would affect any of the following: + +- `prisma/schema.prisma` enums or persisted model contracts +- `src/intents/intents.gateway.ts` WebSocket message shapes or protocol semantics +- `src/soroban/` behavior, contract assumptions, or on-chain interaction semantics +- any change that alters the public meaning of an `IntentState` or request/response payload + +Minor bug fixes, cleanup, or isolated refactors do not usually require an RFC. + +## Lifecycle + +1. Draft: the contributor writes the proposal in `docs/rfcs/` using the template. +2. Discussion: reviewers comment on the RFC in the pull request or linked discussion. +3. Accepted: the design is approved and implementation may proceed. +4. Rejected: the design is not approved and the idea should be closed or revised. +5. Implemented: the linked pull request lands with the RFC in place. + +## Worked examples + +The following issue areas are examples of design work that should have an RFC before implementation begins: + +- #7: routing and quote-flow changes +- #44: on-chain intent registration +- #77: pending intent lifecycle changes + +## Files + +- `docs/rfcs/0000-template.md` — base template for new proposals + +A new RFC should be short and focused: motivation, proposed change, alternatives, and backward-compatibility impact.