Skip to content

Feature/dojoup update command #3251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
Closed

Feature/dojoup update command #3251

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2e23796
docs: update DEVELOPMENT.md and CONTRIBUTING.md after repo split
ritik4ever Jun 20, 2025
d829218
fix Development setup
ritik4ever Jun 20, 2025
d9af650
feat: add 'dojoup update' command for seamless Dojo updates
ritik4ever Jun 21, 2025
554f1b1
feat: add 'dojoup update' command for seamless Dojo updates
ritik4ever Jun 21, 2025
bf5fe0a
fix the issue
ritik4ever Jun 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 114 additions & 31 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:

Expand All @@ -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!
Loading