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..1f8480f923 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,97 +1,178 @@ # Development Setup -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. +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. -## System prerequisites +## Repository Structure -- [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 +After recent architectural improvements, the Dojo ecosystem consists of several repositories: -See the [Dojo Installation guide](https://book.dojoengine.org/installation) for more details on installing these dependencies. +- **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 -> Depending on your Linux distribution, you may need to install additional dependencies. +## System Prerequisites -## Setting up your environment +- **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 -### 1. Clone the repository +See the [Dojo Installation guide](https://book.dojoengine.org/getting-started) for more details on installing these dependencies. -```sh +### Installing External Components + +Since Katana and Torii are now in separate repositories, you have two options: + +#### Option 1: Install via dojoup (Recommended) +```bash +curl -L https://install.dojoengine.org | bash +dojoup +``` + +#### 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 + +### 1. Clone the Repository + +```bash git clone https://github.com/dojoengine/dojo.git && cd dojo ``` -### 2. Run the tests +### 2. Architecture Overview + +At the top level, this repository is organized as follows: + +- **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 + +**Note**: Katana and Torii are now maintained in separate repositories: +- Katana: https://github.com/dojoengine/katana +- Torii: https://github.com/dojoengine/torii -We're using `nextest` as our test runner, which you can get at [https://nexte.st/](https://nexte.st/). +### 3. Run the Tests -> Note that the tests depend on database artifacts for a simple "spawn and move" game. +We use `nextest` as our test runner. Install it from https://nexte.st/. -```sh +Note that tests depend on database artifacts for a simple "spawn and move" game: + +```bash # Prepare the spawn-and-move db artifact bash scripts/extract_test_db.sh -# Run all the tests +# Run all tests cargo nextest run --all-features --workspace # Run a single package test cargo nextest run --all-features -p sozo-ops ``` -## Testing your changes +## Testing Your Changes -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: +Before submitting a pull request, run the tests locally to ensure your changes work correctly: ```bash +# Run the same command that CI uses cargo nextest run --all-features --workspace --build-jobs 20 ``` -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. +The built-in Continuous Integration (CI) will run all tests when you push changes. Test results appear in your pull request's GitHub interface. -> 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). +## Rebuilding Artifacts -### Rebuilding artifacts +If you modified the `dojo-core` or `dojo-lang` crates, you must rebuild the database artifacts. -If you modified the `dojo-core` or `dojo-lang` crates, you must rebuild the db artifacts. -This will require a compatible version of Katana. - -If you have a compatible version of Katana in your `$PATH`, simply run the following command: +### Method 1: Using System Katana +If you have a compatible Katana version in your `$PATH`: ```bash -# Rebuild the spawn-and-move db artifact bash scripts/rebuild_test_artifacts.sh ``` -> If you receive error messages saying `No version is set for command scarb`, run `asdf current` to check your installed versions. +If you see "No version is set for command scarb", run `asdf current` to check versions. -Otherwise, you will need to build Katana from source and copy it to the `/tmp/` directory. -In a new terminal window, run: +### Method 2: Build Katana from Source +If you need a specific Katana version: -```sh +```bash +# In a new terminal git clone https://github.com/dojoengine/katana.git && cd katana - -# Build a new katana binary from source cargo build --bin katana -r - -# Copy the binary to the /tmp/ directory cp target/release/katana /tmp/ ``` -Then you can run the `rebuild_test_artifacts` script from the Dojo directory. +Then run the rebuild script from the Dojo directory. + +**Note**: Dojo looks for test dependencies (katana binary and spawn-and-move artifact) in `/tmp/` by convention. + +## Development Workflow + +### Working with Core Components +For changes to ECS framework, smart contracts, or Sozo: + +```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 +``` + +### Full Stack Development +For end-to-end testing with the complete Dojo stack: -> Note: By convention, Dojo looks for its test dependencies -- the `katana` binary and the `spawn-and-move` artifact -- in your system's `/tmp/` directory. +```bash +# Terminal 1: Start Katana +katana --dev -> 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). +# Terminal 2: Build and deploy your world +cd examples/spawn-and-move +sozo build && sozo migrate + +# Terminal 3: Start Torii indexer +torii --world + +# Terminal 4: Run your client application (if applicable) +cd client && yarn dev +``` + +### 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) ## Releasing -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]`. +Propose a new release by manually triggering the `release-dispatch` GitHub action. The version value can be semver or a level: `[patch, minor, major]`. + +Once run, the workflow creates a PR with the versioned repo, which triggers the release flow and creates a draft release on merge. + +## Getting Help -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. +- **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