From 2e2379691b809a7455e21660942a088f7ba0255d Mon Sep 17 00:00:00 2001 From: Ritk Patel Date: Fri, 20 Jun 2025 15:39:25 +0530 Subject: [PATCH 1/2] docs: update DEVELOPMENT.md and CONTRIBUTING.md after repo split - Remove build instructions for Katana and Torii from main repo - Add references to separate Katana and Torii repositories - Update development setup to focus on core Dojo components - Clarify contribution guidelines for split architecture - Add guidance on which repository to use for different issues Fixes #3228 --- CONTRIBUTING.md | 145 +++++++++++++++++++++++++-------- DEVELOPMENT.md | 207 ++++++++++++++++++++++++++++++++++-------------- 2 files changed, 261 insertions(+), 91 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d72f5783f1..10727fd506 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,44 +4,84 @@ Thank you for considering contributing to Dojo. It's people like you that make D Please follow the following guidelines in order to streamline your contribution. It helps communicate that you respect the time of the developers maintaining this open source project. In return, maintainers will reciprocate that respect when addressing your issue, assessing your changes, and helping you finalize your pull requests. -### Check existing issues +## Repository Architecture -Before you start contributing, please check the [Issue Tracker](https://github.com/dojoengine/dojo/issues) to see if there are any existing issues that match what you are intending to do. If the issue doesn't exist, please create it. +The Dojo ecosystem is organized across multiple repositories to improve maintainability and development efficiency: + +| Component | Repository | Purpose | +|-----------|------------|---------| +| **Core Framework** | [dojoengine/dojo](https://github.com/dojoengine/dojo) | ECS framework, Sozo CLI, smart contracts | +| **Katana** | [dojoengine/katana](https://github.com/dojoengine/katana) | High-performance sequencer | +| **Torii** | [dojoengine/torii](https://github.com/dojoengine/torii) | Automatic indexer and API layer | +| **Client SDKs** | [dojoengine/dojo.js](https://github.com/dojoengine/dojo.js) | JavaScript/TypeScript SDK | +| **Documentation** | [dojoengine/book](https://github.com/dojoengine/book) | Official documentation | + +## Which Repository Should I Use? + +### Core Framework (This Repository) +Contribute here for: +- ✅ ECS framework improvements +- ✅ Sozo CLI features and bug fixes +- ✅ Smart contract templates and examples +- ✅ Core compilation and build tools +- ✅ Integration issues between components + +### External Repositories +| Type of Contribution | Repository | Examples | +|---------------------|------------|----------| +| Sequencer issues | [katana](https://github.com/dojoengine/katana) | Block production, RPC endpoints, performance | +| Indexing/API issues | [torii](https://github.com/dojoengine/torii) | GraphQL queries, event indexing, subscriptions | +| Client SDK issues | [dojo.js](https://github.com/dojoengine/dojo.js) | JavaScript SDK, React hooks, TypeScript types | +| Documentation | [book](https://github.com/dojoengine/book) | Tutorials, guides, API documentation | + +## Check Existing Issues + +Before you start contributing, please check the Issue Tracker to see if there are any existing issues that match what you are intending to do. If the issue doesn't exist, please create it. If you are creating a new issue, please provide a descriptive title and detailed description. If possible, include a code sample or an executable test case demonstrating the expected behavior that is not occurring. -### Fork and Clone the Repository +### Issue Reporting Guidelines -Once you've found an issue to work on, the next step is to fork the Dojo repo and clone it to your local machine. This is necessary because you probably won't have push access to the main repo. +| Issue Type | Repository | Examples | +|------------|------------|----------| +| Framework bugs | [dojo](https://github.com/dojoengine/dojo/issues) | ECS bugs, Sozo crashes, compilation errors | +| Performance issues | [katana](https://github.com/dojoengine/katana/issues) | Slow block production, RPC timeouts | +| Query problems | [torii](https://github.com/dojoengine/torii/issues) | GraphQL errors, missing events, sync issues | +| SDK issues | [dojo.js](https://github.com/dojoengine/dojo.js/issues) | TypeScript errors, React hooks, integration | +| Documentation gaps | [book](https://github.com/dojoengine/book/issues) | Missing guides, unclear examples | -### Setting up your environment +## Fork and Clone the Repository -You will need the [Rust](https://rust-lang.org) compiler and Cargo, the Rust package manager. -The easiest way to install both is with [`rustup.rs`](https://rustup.rs/). +Once you've found an issue to work on, the next step is to fork the appropriate repository and clone it to your local machine. This is necessary because you probably won't have push access to the main repo. -On Windows, you will also need a recent version of [Visual Studio](https://visualstudio.microsoft.com/downloads/), -installed with the "Desktop Development With C++" Workloads option. +## Setting Up Your Environment + +You will need the Rust compiler and Cargo, the Rust package manager. The easiest way to install both is with [rustup.rs](https://rustup.rs/). + +On Windows, you will also need a recent version of Visual Studio, installed with the "Desktop Development With C++" Workloads option. + +See our [Development Guide](./DEVELOPMENT.md) for detailed setup instructions. ## Architecture -At the top level, dojo is composed of different folders: +At the top level, this repository is composed of different folders: -- [`crates`](crates/): This folder contains the source code of the different crates (which are libraries) that make up Dojo. -- [`bin`](bin/): This folder contains the source code of the different binaries that make up Dojo. -- [`examples`](examples/): This folder contains the source code of simple Dojo projects that can be used as a starting point for new projects and also useful for testing. -- [`scripts`](scripts/): A set of useful scripts for developers and CI. +- **crates**: Source code of the different libraries that make up core Dojo +- **bin**: Source code of the different binaries (primarily Sozo) +- **examples**: Simple Dojo projects for testing and reference +- **scripts**: Useful scripts for developers and CI -Inside `bin` and `crates` you will find source code related to Dojo stack components: +Inside bin and crates you will find source code related to core Dojo components: -- `katana`: The Starknet sequencer tailored for gaming. -- `sozo`: The contract manager and Dojo compiler. -- `torii`: The indexer that store the state of your World. -- `dojo/core`: The core contract of Dojo written in Cairo. -- `dojo/lang`: The Dojo plugin for the Cairo compiler. +- **sozo**: The contract manager and Dojo compiler +- **dojo/core**: The core contracts written in Cairo +- **dojo/lang**: The Dojo plugin for the Cairo compiler -It is important to note that `bin` should only contain applications that gathers user inputs and delegates the work to the libraries present into the crates. +**Important**: The following components are now maintained in separate repositories: +- **katana**: The Starknet sequencer (now at [dojoengine/katana](https://github.com/dojoengine/katana)) +- **torii**: The indexer that stores World state (now at [dojoengine/torii](https://github.com/dojoengine/torii)) -As an example, `sozo` is a CLI that gathers user inputs and delegates the work to run the commands code to the `sozo` crate. +It is important to note that `bin` should only contain applications that gather user inputs and delegate work to the libraries present in `crates`. As an example, `sozo` is a CLI that gathers user inputs and delegates the work to run commands to the `sozo` crate. ## Making Changes @@ -51,9 +91,9 @@ Please use meaningful names for your branches. For example, if you're working on As you're making changes, make sure you follow the coding conventions used throughout the Dojo project. Consistent code style makes it easier for others to read and understand your code. -## Testing the changes +## Testing the Changes -To speed the test suite and avoid migrating dojo projects again, `katana` databases are compressed and stored in the repo. +To speed the test suite and avoid migrating dojo projects again, katana databases are compressed and stored in the repo. If you don't have any change in the `dojo/core` crate or any cairo example, you only have to extract the databases: @@ -77,25 +117,68 @@ Then you can run the tests: # If you don't have any change in Katana: cargo nextest run --all-features --build-jobs 20 --workspace -# If you have changes in Katana, you must use local Katana to test. -cargo build -r --bin katana -KATANA_RUNNER_BIN=./target/release/katana cargo nextest run --all-features --build-jobs 20 --workspace +# If you have changes that require testing with Katana, you must use a local Katana binary. +# First, build or obtain a compatible Katana binary (see DEVELOPMENT.md for details) +cargo build -r --bin katana # This will fail if Katana is not in this repo +# Use system Katana or build from separate repository instead +KATANA_RUNNER_BIN=katana cargo nextest run --all-features --build-jobs 20 --workspace ``` +**Note**: Since Katana is now in a separate repository, you'll need to install it separately or build it from the [Katana repository](https://github.com/dojoengine/katana) if tests require it. + ## Submitting a Pull Request -Once your changes are ready, commit them and push the branch to your forked repo on GitHub. Then you can open a pull request from your branch to the `main` branch of the Dojo repo. +Once your changes are ready, commit them and push the branch to your forked repo on GitHub. Then you can open a pull request from your branch to the main branch of the Dojo repo. When you submit the pull request, please provide a clear, detailed description of the changes you've made. If you're addressing a specific issue, make sure you reference it in the description. Your pull request will be reviewed by the maintainers of the Dojo project. They may ask for changes or clarification on certain points. Please address their comments and commit any required changes to the same branch on your repo. +## Cross-Repository Contributions + +Some features may require changes across multiple repositories: + +### Example: Adding a New ECS Feature +1. **Core Framework** (this repo): Implement the ECS feature +2. **Katana** (if needed): Add sequencer support for new events +3. **Torii** (if needed): Add indexing for new data structures +4. **dojo.js** (if needed): Add client SDK support +5. **Documentation**: Update guides and examples + +### Coordination Process +1. Create issues in each relevant repository +2. Reference cross-repository issues in descriptions +3. Coordinate with maintainers for release planning +4. Test integration between components + ## Documentation We strive to provide comprehensive, up-to-date documentation for Dojo. If your changes require updates to the documentation, please include those in your pull request. -The [Dojo Book repository](https://github.com/dojoengine/book) is where you should submit your changes to the documentation. - +The [Dojo Book repository](https://github.com/dojoengine/book) is where you should submit your changes to user-facing documentation. ## Final Notes -Again, thank you for considering to contribute to Dojo. Your contribution is invaluable to us. We hope this guide makes the contribution process clear and answers any questions you might have. If not, feel free to ask on the [Discord](https://discord.com/invite/dojoengine) or on [GitHub](https://github.com/dojoengine/dojo/issues). +Again, thank you for considering contributing to Dojo. Your contribution is invaluable to us. We hope this guide makes the contribution process clear and answers any questions you might have. + +If you have questions about: +- **Which repository to use**: Ask in our [Discord #dev-help channel](https://discord.gg/dojoengine) +- **Technical approach**: Create a discussion issue before coding +- **Contribution scope**: Reach out to maintainers + +For more detailed development setup instructions, see our [Development Guide](./DEVELOPMENT.md). + +## Community and Communication + +### Getting Help +- **Discord**: Join our [Discord community](https://discord.gg/dojoengine) for real-time discussions +- **GitHub Discussions**: Use GitHub Discussions for longer-form questions +- **Documentation**: Check the [Dojo Book](https://book.dojoengine.org) for comprehensive guides + +### Recognition + +Contributors are recognized through: +- **GitHub**: Automatic contribution tracking +- **Discord**: Special contributor roles +- **Documentation**: Major contributors listed in project documentation + +Thank you for contributing to Dojo! \ No newline at end of file diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 2109b1e3e2..10727fd506 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,97 +1,184 @@ -# Development Setup +# Contributing to Dojo -This guide outlines the steps for setting up an environment for developing the Dojo codebase. -If you want to use Dojo to make things, follow the [Dojo Installation guide](https://book.dojoengine.org/installation) instead. +Thank you for considering contributing to Dojo. It's people like you that make Dojo such a great project and community. -## System prerequisites +Please follow the following guidelines in order to streamline your contribution. It helps communicate that you respect the time of the developers maintaining this open source project. In return, maintainers will reciprocate that respect when addressing your issue, assessing your changes, and helping you finalize your pull requests. -- [Rust](https://github.com/rust-lang/rust) -- [Cairo](https://github.com/starkware-libs/cairo) -- [Katana](https://github.com/dojoengine/katana) (via Dojo) -- [protoc](https://github.com/protocolbuffers/protobuf) -- Optional: [VS Code extension](https://marketplace.visualstudio.com/items?itemName=starkware.cairo1) for syntax highlighting +## Repository Architecture -See the [Dojo Installation guide](https://book.dojoengine.org/installation) for more details on installing these dependencies. +The Dojo ecosystem is organized across multiple repositories to improve maintainability and development efficiency: -> Depending on your Linux distribution, you may need to install additional dependencies. +| Component | Repository | Purpose | +|-----------|------------|---------| +| **Core Framework** | [dojoengine/dojo](https://github.com/dojoengine/dojo) | ECS framework, Sozo CLI, smart contracts | +| **Katana** | [dojoengine/katana](https://github.com/dojoengine/katana) | High-performance sequencer | +| **Torii** | [dojoengine/torii](https://github.com/dojoengine/torii) | Automatic indexer and API layer | +| **Client SDKs** | [dojoengine/dojo.js](https://github.com/dojoengine/dojo.js) | JavaScript/TypeScript SDK | +| **Documentation** | [dojoengine/book](https://github.com/dojoengine/book) | Official documentation | -## Setting up your environment +## Which Repository Should I Use? -### 1. Clone the repository +### Core Framework (This Repository) +Contribute here for: +- ✅ ECS framework improvements +- ✅ Sozo CLI features and bug fixes +- ✅ Smart contract templates and examples +- ✅ Core compilation and build tools +- ✅ Integration issues between components -```sh -git clone https://github.com/dojoengine/dojo.git && cd dojo -``` +### External Repositories +| Type of Contribution | Repository | Examples | +|---------------------|------------|----------| +| Sequencer issues | [katana](https://github.com/dojoengine/katana) | Block production, RPC endpoints, performance | +| Indexing/API issues | [torii](https://github.com/dojoengine/torii) | GraphQL queries, event indexing, subscriptions | +| Client SDK issues | [dojo.js](https://github.com/dojoengine/dojo.js) | JavaScript SDK, React hooks, TypeScript types | +| Documentation | [book](https://github.com/dojoengine/book) | Tutorials, guides, API documentation | -### 2. Run the tests +## Check Existing Issues -We're using `nextest` as our test runner, which you can get at [https://nexte.st/](https://nexte.st/). +Before you start contributing, please check the Issue Tracker to see if there are any existing issues that match what you are intending to do. If the issue doesn't exist, please create it. -> Note that the tests depend on database artifacts for a simple "spawn and move" game. +If you are creating a new issue, please provide a descriptive title and detailed description. If possible, include a code sample or an executable test case demonstrating the expected behavior that is not occurring. -```sh -# Prepare the spawn-and-move db artifact -bash scripts/extract_test_db.sh +### Issue Reporting Guidelines -# Run all the tests -cargo nextest run --all-features --workspace +| Issue Type | Repository | Examples | +|------------|------------|----------| +| Framework bugs | [dojo](https://github.com/dojoengine/dojo/issues) | ECS bugs, Sozo crashes, compilation errors | +| Performance issues | [katana](https://github.com/dojoengine/katana/issues) | Slow block production, RPC timeouts | +| Query problems | [torii](https://github.com/dojoengine/torii/issues) | GraphQL errors, missing events, sync issues | +| SDK issues | [dojo.js](https://github.com/dojoengine/dojo.js/issues) | TypeScript errors, React hooks, integration | +| Documentation gaps | [book](https://github.com/dojoengine/book/issues) | Missing guides, unclear examples | -# Run a single package test -cargo nextest run --all-features -p sozo-ops -``` +## Fork and Clone the Repository -## Testing your changes +Once you've found an issue to work on, the next step is to fork the appropriate repository and clone it to your local machine. This is necessary because you probably won't have push access to the main repo. -Before you submit your pull request, you should run the tests locally to make sure your changes haven't broken anything. -You can execute the same command that will be executed on the CI by checking the [`.github/workflows/test.yml`](.github/workflows/test.yml) file: +## Setting Up Your Environment -```bash -cargo nextest run --all-features --workspace --build-jobs 20 -``` +You will need the Rust compiler and Cargo, the Rust package manager. The easiest way to install both is with [rustup.rs](https://rustup.rs/). + +On Windows, you will also need a recent version of Visual Studio, installed with the "Desktop Development With C++" Workloads option. + +See our [Development Guide](./DEVELOPMENT.md) for detailed setup instructions. + +## Architecture + +At the top level, this repository is composed of different folders: -When you push your changes, the built-in Continuous Integration (CI) will run all the tests on your new code. -You can see the result of these tests in the GitHub interface of your pull request. -If the tests fail, you'll need to revise your code and push it again. +- **crates**: Source code of the different libraries that make up core Dojo +- **bin**: Source code of the different binaries (primarily Sozo) +- **examples**: Simple Dojo projects for testing and reference +- **scripts**: Useful scripts for developers and CI -> The CI uses a `devcontainer` to have all the dependencies installed and to run the tests. -> You can find more information about the devcontainer in the [`.devcontainer.json`](.devcontainer/devcontainer.json) file and see the latest releases on [GitHub package](https://github.com/dojoengine/dojo/pkgs/container/dojo-dev). +Inside bin and crates you will find source code related to core Dojo components: -### Rebuilding artifacts +- **sozo**: The contract manager and Dojo compiler +- **dojo/core**: The core contracts written in Cairo +- **dojo/lang**: The Dojo plugin for the Cairo compiler -If you modified the `dojo-core` or `dojo-lang` crates, you must rebuild the db artifacts. -This will require a compatible version of Katana. +**Important**: The following components are now maintained in separate repositories: +- **katana**: The Starknet sequencer (now at [dojoengine/katana](https://github.com/dojoengine/katana)) +- **torii**: The indexer that stores World state (now at [dojoengine/torii](https://github.com/dojoengine/torii)) -If you have a compatible version of Katana in your `$PATH`, simply run the following command: +It is important to note that `bin` should only contain applications that gather user inputs and delegate work to the libraries present in `crates`. As an example, `sozo` is a CLI that gathers user inputs and delegates the work to run commands to the `sozo` crate. + +## Making Changes + +When you're ready to start coding, create a new branch on your cloned repo. It's important to use a separate branch for each issue you're working on. This keeps your changes separate in case you want to submit more than one contribution. + +Please use meaningful names for your branches. For example, if you're working on a bug with the ECS, you might name your branch `fix-ecs-bug`. + +As you're making changes, make sure you follow the coding conventions used throughout the Dojo project. Consistent code style makes it easier for others to read and understand your code. + +## Testing the Changes + +To speed the test suite and avoid migrating dojo projects again, katana databases are compressed and stored in the repo. + +If you don't have any change in the `dojo/core` crate or any cairo example, you only have to extract the databases: ```bash -# Rebuild the spawn-and-move db artifact -bash scripts/rebuild_test_artifacts.sh +bash scripts/extract_test_db.sh ``` -> If you receive error messages saying `No version is set for command scarb`, run `asdf current` to check your installed versions. +To test your changes, if you have modified the `dojo/core` crate or any cairo example, you will need to regenerate the databases: -Otherwise, you will need to build Katana from source and copy it to the `/tmp/` directory. -In a new terminal window, run: +```bash +# Prints the policies to then be copied into the `sozo/tests/test_data/policies.json` test file to ensure entrypoints and addresses are up to date. +POLICIES_FIX=1 cargo nextest run --all-features --build-jobs 20 --workspace --nocapture policies -```sh -git clone https://github.com/dojoengine/katana.git && cd katana +# Ensures the test databases are up to date. +bash scripts/rebuild_test_artifacts.sh +``` -# Build a new katana binary from source -cargo build --bin katana -r +Then you can run the tests: -# Copy the binary to the /tmp/ directory -cp target/release/katana /tmp/ +```bash +# If you don't have any change in Katana: +cargo nextest run --all-features --build-jobs 20 --workspace + +# If you have changes that require testing with Katana, you must use a local Katana binary. +# First, build or obtain a compatible Katana binary (see DEVELOPMENT.md for details) +cargo build -r --bin katana # This will fail if Katana is not in this repo +# Use system Katana or build from separate repository instead +KATANA_RUNNER_BIN=katana cargo nextest run --all-features --build-jobs 20 --workspace ``` -Then you can run the `rebuild_test_artifacts` script from the Dojo directory. +**Note**: Since Katana is now in a separate repository, you'll need to install it separately or build it from the [Katana repository](https://github.com/dojoengine/katana) if tests require it. + +## Submitting a Pull Request + +Once your changes are ready, commit them and push the branch to your forked repo on GitHub. Then you can open a pull request from your branch to the main branch of the Dojo repo. + +When you submit the pull request, please provide a clear, detailed description of the changes you've made. If you're addressing a specific issue, make sure you reference it in the description. + +Your pull request will be reviewed by the maintainers of the Dojo project. They may ask for changes or clarification on certain points. Please address their comments and commit any required changes to the same branch on your repo. + +## Cross-Repository Contributions + +Some features may require changes across multiple repositories: + +### Example: Adding a New ECS Feature +1. **Core Framework** (this repo): Implement the ECS feature +2. **Katana** (if needed): Add sequencer support for new events +3. **Torii** (if needed): Add indexing for new data structures +4. **dojo.js** (if needed): Add client SDK support +5. **Documentation**: Update guides and examples + +### Coordination Process +1. Create issues in each relevant repository +2. Reference cross-repository issues in descriptions +3. Coordinate with maintainers for release planning +4. Test integration between components + +## Documentation + +We strive to provide comprehensive, up-to-date documentation for Dojo. If your changes require updates to the documentation, please include those in your pull request. + +The [Dojo Book repository](https://github.com/dojoengine/book) is where you should submit your changes to user-facing documentation. +## Final Notes + +Again, thank you for considering contributing to Dojo. Your contribution is invaluable to us. We hope this guide makes the contribution process clear and answers any questions you might have. + +If you have questions about: +- **Which repository to use**: Ask in our [Discord #dev-help channel](https://discord.gg/dojoengine) +- **Technical approach**: Create a discussion issue before coding +- **Contribution scope**: Reach out to maintainers + +For more detailed development setup instructions, see our [Development Guide](./DEVELOPMENT.md). -> Note: By convention, Dojo looks for its test dependencies -- the `katana` binary and the `spawn-and-move` artifact -- in your system's `/tmp/` directory. +## Community and Communication -> Note: Katana depends on [Bun](https://bun.sh/) for development, which you may need to install. -> For more information, see [the Katana README](https://github.com/dojoengine/katana). +### Getting Help +- **Discord**: Join our [Discord community](https://discord.gg/dojoengine) for real-time discussions +- **GitHub Discussions**: Use GitHub Discussions for longer-form questions +- **Documentation**: Check the [Dojo Book](https://book.dojoengine.org) for comprehensive guides -## Releasing +### Recognition -Propose a new release by manually triggering the `release-dispatch` github action. The version value can be an semver or a level: `[patch, minor, major]`. +Contributors are recognized through: +- **GitHub**: Automatic contribution tracking +- **Discord**: Special contributor roles +- **Documentation**: Major contributors listed in project documentation -Once run, the workflow will create a PR with the versioned repo which will trigger the release flow and the creation of a draft release on merge. +Thank you for contributing to Dojo! \ No newline at end of file From d829218bdabfd00035e2fe5bce695b87a3340462 Mon Sep 17 00:00:00 2001 From: Ritk Patel Date: Fri, 20 Jun 2025 15:48:31 +0530 Subject: [PATCH 2/2] fix Development setup --- DEVELOPMENT.md | 242 ++++++++++++++++++++++++------------------------- 1 file changed, 118 insertions(+), 124 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 10727fd506..1f8480f923 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,184 +1,178 @@ -# Contributing to Dojo +# Development Setup -Thank you for considering contributing to Dojo. It's people like you that make Dojo such a great project and community. +This guide outlines the steps for setting up an environment for developing the Dojo codebase. If you want to use Dojo to make things, follow the [Dojo Installation guide](https://book.dojoengine.org/getting-started) instead. -Please follow the following guidelines in order to streamline your contribution. It helps communicate that you respect the time of the developers maintaining this open source project. In return, maintainers will reciprocate that respect when addressing your issue, assessing your changes, and helping you finalize your pull requests. +## Repository Structure -## Repository Architecture +After recent architectural improvements, the Dojo ecosystem consists of several repositories: -The Dojo ecosystem is organized across multiple repositories to improve maintainability and development efficiency: +- **This Repository (dojoengine/dojo)**: Core Dojo framework, Sozo CLI, ECS components, and smart contracts +- **Katana Repository** ([dojoengine/katana](https://github.com/dojoengine/katana)): High-performance sequencer for Dojo +- **Torii Repository** ([dojoengine/torii](https://github.com/dojoengine/torii)): Automatic indexer and GraphQL/gRPC API -| Component | Repository | Purpose | -|-----------|------------|---------| -| **Core Framework** | [dojoengine/dojo](https://github.com/dojoengine/dojo) | ECS framework, Sozo CLI, smart contracts | -| **Katana** | [dojoengine/katana](https://github.com/dojoengine/katana) | High-performance sequencer | -| **Torii** | [dojoengine/torii](https://github.com/dojoengine/torii) | Automatic indexer and API layer | -| **Client SDKs** | [dojoengine/dojo.js](https://github.com/dojoengine/dojo.js) | JavaScript/TypeScript SDK | -| **Documentation** | [dojoengine/book](https://github.com/dojoengine/book) | Official documentation | +## System Prerequisites -## Which Repository Should I Use? +- **Rust** (latest stable version) +- **Cairo** (via dojoup) +- **Katana** (installed separately - see below) +- **Torii** (installed separately - see below) +- **protoc** (Protocol Buffers compiler) +- **Optional**: VS Code extension for syntax highlighting -### Core Framework (This Repository) -Contribute here for: -- ✅ ECS framework improvements -- ✅ Sozo CLI features and bug fixes -- ✅ Smart contract templates and examples -- ✅ Core compilation and build tools -- ✅ Integration issues between components +See the [Dojo Installation guide](https://book.dojoengine.org/getting-started) for more details on installing these dependencies. -### External Repositories -| Type of Contribution | Repository | Examples | -|---------------------|------------|----------| -| Sequencer issues | [katana](https://github.com/dojoengine/katana) | Block production, RPC endpoints, performance | -| Indexing/API issues | [torii](https://github.com/dojoengine/torii) | GraphQL queries, event indexing, subscriptions | -| Client SDK issues | [dojo.js](https://github.com/dojoengine/dojo.js) | JavaScript SDK, React hooks, TypeScript types | -| Documentation | [book](https://github.com/dojoengine/book) | Tutorials, guides, API documentation | +### Installing External Components -## Check Existing Issues +Since Katana and Torii are now in separate repositories, you have two options: -Before you start contributing, please check the Issue Tracker to see if there are any existing issues that match what you are intending to do. If the issue doesn't exist, please create it. - -If you are creating a new issue, please provide a descriptive title and detailed description. If possible, include a code sample or an executable test case demonstrating the expected behavior that is not occurring. - -### Issue Reporting Guidelines - -| Issue Type | Repository | Examples | -|------------|------------|----------| -| Framework bugs | [dojo](https://github.com/dojoengine/dojo/issues) | ECS bugs, Sozo crashes, compilation errors | -| Performance issues | [katana](https://github.com/dojoengine/katana/issues) | Slow block production, RPC timeouts | -| Query problems | [torii](https://github.com/dojoengine/torii/issues) | GraphQL errors, missing events, sync issues | -| SDK issues | [dojo.js](https://github.com/dojoengine/dojo.js/issues) | TypeScript errors, React hooks, integration | -| Documentation gaps | [book](https://github.com/dojoengine/book/issues) | Missing guides, unclear examples | - -## Fork and Clone the Repository +#### Option 1: Install via dojoup (Recommended) +```bash +curl -L https://install.dojoengine.org | bash +dojoup +``` -Once you've found an issue to work on, the next step is to fork the appropriate repository and clone it to your local machine. This is necessary because you probably won't have push access to the main repo. +#### Option 2: Install from source +```bash +# Install Katana from source +git clone https://github.com/dojoengine/katana.git +cd katana +cargo install --path . --locked --force + +# Install Torii from source +git clone https://github.com/dojoengine/torii.git +cd torii +cargo install --path . --locked --force +``` ## Setting Up Your Environment -You will need the Rust compiler and Cargo, the Rust package manager. The easiest way to install both is with [rustup.rs](https://rustup.rs/). - -On Windows, you will also need a recent version of Visual Studio, installed with the "Desktop Development With C++" Workloads option. +### 1. Clone the Repository -See our [Development Guide](./DEVELOPMENT.md) for detailed setup instructions. - -## Architecture +```bash +git clone https://github.com/dojoengine/dojo.git && cd dojo +``` -At the top level, this repository is composed of different folders: +### 2. Architecture Overview -- **crates**: Source code of the different libraries that make up core Dojo -- **bin**: Source code of the different binaries (primarily Sozo) -- **examples**: Simple Dojo projects for testing and reference -- **scripts**: Useful scripts for developers and CI +At the top level, this repository is organized as follows: -Inside bin and crates you will find source code related to core Dojo components: +- **crates/**: Source code of the different libraries that make up core Dojo +- **bin/**: Source code of the different binaries (primarily Sozo) +- **examples/**: Simple Dojo projects for testing and reference +- **scripts/**: Useful scripts for developers and CI +Key components in this repository: - **sozo**: The contract manager and Dojo compiler - **dojo/core**: The core contracts written in Cairo - **dojo/lang**: The Dojo plugin for the Cairo compiler -**Important**: The following components are now maintained in separate repositories: -- **katana**: The Starknet sequencer (now at [dojoengine/katana](https://github.com/dojoengine/katana)) -- **torii**: The indexer that stores World state (now at [dojoengine/torii](https://github.com/dojoengine/torii)) +**Note**: Katana and Torii are now maintained in separate repositories: +- Katana: https://github.com/dojoengine/katana +- Torii: https://github.com/dojoengine/torii -It is important to note that `bin` should only contain applications that gather user inputs and delegate work to the libraries present in `crates`. As an example, `sozo` is a CLI that gathers user inputs and delegates the work to run commands to the `sozo` crate. +### 3. Run the Tests -## Making Changes +We use `nextest` as our test runner. Install it from https://nexte.st/. -When you're ready to start coding, create a new branch on your cloned repo. It's important to use a separate branch for each issue you're working on. This keeps your changes separate in case you want to submit more than one contribution. +Note that tests depend on database artifacts for a simple "spawn and move" game: -Please use meaningful names for your branches. For example, if you're working on a bug with the ECS, you might name your branch `fix-ecs-bug`. +```bash +# Prepare the spawn-and-move db artifact +bash scripts/extract_test_db.sh -As you're making changes, make sure you follow the coding conventions used throughout the Dojo project. Consistent code style makes it easier for others to read and understand your code. +# Run all tests +cargo nextest run --all-features --workspace -## Testing the Changes +# Run a single package test +cargo nextest run --all-features -p sozo-ops +``` -To speed the test suite and avoid migrating dojo projects again, katana databases are compressed and stored in the repo. +## Testing Your Changes -If you don't have any change in the `dojo/core` crate or any cairo example, you only have to extract the databases: +Before submitting a pull request, run the tests locally to ensure your changes work correctly: ```bash -bash scripts/extract_test_db.sh +# Run the same command that CI uses +cargo nextest run --all-features --workspace --build-jobs 20 ``` -To test your changes, if you have modified the `dojo/core` crate or any cairo example, you will need to regenerate the databases: +The built-in Continuous Integration (CI) will run all tests when you push changes. Test results appear in your pull request's GitHub interface. -```bash -# Prints the policies to then be copied into the `sozo/tests/test_data/policies.json` test file to ensure entrypoints and addresses are up to date. -POLICIES_FIX=1 cargo nextest run --all-features --build-jobs 20 --workspace --nocapture policies +## Rebuilding Artifacts -# Ensures the test databases are up to date. -bash scripts/rebuild_test_artifacts.sh -``` +If you modified the `dojo-core` or `dojo-lang` crates, you must rebuild the database artifacts. -Then you can run the tests: +### Method 1: Using System Katana +If you have a compatible Katana version in your `$PATH`: ```bash -# If you don't have any change in Katana: -cargo nextest run --all-features --build-jobs 20 --workspace - -# If you have changes that require testing with Katana, you must use a local Katana binary. -# First, build or obtain a compatible Katana binary (see DEVELOPMENT.md for details) -cargo build -r --bin katana # This will fail if Katana is not in this repo -# Use system Katana or build from separate repository instead -KATANA_RUNNER_BIN=katana cargo nextest run --all-features --build-jobs 20 --workspace +bash scripts/rebuild_test_artifacts.sh ``` -**Note**: Since Katana is now in a separate repository, you'll need to install it separately or build it from the [Katana repository](https://github.com/dojoengine/katana) if tests require it. - -## Submitting a Pull Request +If you see "No version is set for command scarb", run `asdf current` to check versions. -Once your changes are ready, commit them and push the branch to your forked repo on GitHub. Then you can open a pull request from your branch to the main branch of the Dojo repo. +### Method 2: Build Katana from Source +If you need a specific Katana version: -When you submit the pull request, please provide a clear, detailed description of the changes you've made. If you're addressing a specific issue, make sure you reference it in the description. +```bash +# In a new terminal +git clone https://github.com/dojoengine/katana.git && cd katana +cargo build --bin katana -r +cp target/release/katana /tmp/ +``` -Your pull request will be reviewed by the maintainers of the Dojo project. They may ask for changes or clarification on certain points. Please address their comments and commit any required changes to the same branch on your repo. +Then run the rebuild script from the Dojo directory. -## Cross-Repository Contributions +**Note**: Dojo looks for test dependencies (katana binary and spawn-and-move artifact) in `/tmp/` by convention. -Some features may require changes across multiple repositories: +## Development Workflow -### Example: Adding a New ECS Feature -1. **Core Framework** (this repo): Implement the ECS feature -2. **Katana** (if needed): Add sequencer support for new events -3. **Torii** (if needed): Add indexing for new data structures -4. **dojo.js** (if needed): Add client SDK support -5. **Documentation**: Update guides and examples +### Working with Core Components +For changes to ECS framework, smart contracts, or Sozo: -### Coordination Process -1. Create issues in each relevant repository -2. Reference cross-repository issues in descriptions -3. Coordinate with maintainers for release planning -4. Test integration between components +```bash +# Make changes to relevant crates +# Build and test +cargo build --all +cargo nextest run --all-features --workspace + +# Test with examples +cd examples/spawn-and-move +sozo build +``` -## Documentation +### Full Stack Development +For end-to-end testing with the complete Dojo stack: -We strive to provide comprehensive, up-to-date documentation for Dojo. If your changes require updates to the documentation, please include those in your pull request. +```bash +# Terminal 1: Start Katana +katana --dev -The [Dojo Book repository](https://github.com/dojoengine/book) is where you should submit your changes to user-facing documentation. -## Final Notes +# Terminal 2: Build and deploy your world +cd examples/spawn-and-move +sozo build && sozo migrate -Again, thank you for considering contributing to Dojo. Your contribution is invaluable to us. We hope this guide makes the contribution process clear and answers any questions you might have. +# Terminal 3: Start Torii indexer +torii --world -If you have questions about: -- **Which repository to use**: Ask in our [Discord #dev-help channel](https://discord.gg/dojoengine) -- **Technical approach**: Create a discussion issue before coding -- **Contribution scope**: Reach out to maintainers +# Terminal 4: Run your client application (if applicable) +cd client && yarn dev +``` -For more detailed development setup instructions, see our [Development Guide](./DEVELOPMENT.md). +### Contributing to Related Repositories +- **Katana issues**: [dojoengine/katana](https://github.com/dojoengine/katana) +- **Torii issues**: [dojoengine/torii](https://github.com/dojoengine/torii) +- **Client SDK issues**: [dojoengine/dojo.js](https://github.com/dojoengine/dojo.js) +- **Documentation**: [dojoengine/book](https://github.com/dojoengine/book) -## Community and Communication +## Releasing -### Getting Help -- **Discord**: Join our [Discord community](https://discord.gg/dojoengine) for real-time discussions -- **GitHub Discussions**: Use GitHub Discussions for longer-form questions -- **Documentation**: Check the [Dojo Book](https://book.dojoengine.org) for comprehensive guides +Propose a new release by manually triggering the `release-dispatch` GitHub action. The version value can be semver or a level: `[patch, minor, major]`. -### Recognition +Once run, the workflow creates a PR with the versioned repo, which triggers the release flow and creates a draft release on merge. -Contributors are recognized through: -- **GitHub**: Automatic contribution tracking -- **Discord**: Special contributor roles -- **Documentation**: Major contributors listed in project documentation +## Getting Help -Thank you for contributing to Dojo! \ No newline at end of file +- **Documentation**: [Dojo Book](https://book.dojoengine.org) +- **Discord**: [Dojo Community Discord](https://discord.gg/dojoengine) +- **Issues**: Create issues in the appropriate repository based on the component \ No newline at end of file