Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• ARCHITECTURE.md
• README.md
• apps/backend/README.md
• apps/data-processing/README.md
• apps/dojo/README.md
• apps/frontend/README.md
• apps/backend/package.json
• apps/data-processing/setup.py
• apps/frontend/package.json
• apps/frontend/app/page.tsx
• apps/frontend/app/globals.css
• apps/backend/lint-results.json

OnChain Sage is an open-source, AI-driven, decentralized trading assistant that thrives on community contributions. This guide provides a comprehensive overview of the contribution process, from setting up your development environment to submitting your first pull request. We welcome contributions from developers, designers, and anyone passionate about building a better crypto trading tool.

The project is designed with a modular monorepo structure to encourage collaboration and ensure maintainability. By following these guidelines, you can help us build a robust, scalable, and community-driven platform.

Sources: CONTRIBUTING.md:3-4, README.md:15-18, ARCHITECTURE.md:120-121

Getting Started

Before you can contribute, you need to set up your local development environment. This involves installing prerequisites, forking and cloning the repository, and configuring your local setup.

Sources: README.md:63-65, ARCHITECTURE.md:125-127

Prerequisites

Ensure you have the following software installed on your system.

Software	Version	Notes
Node.js	v14+	Required for frontend and backend services.
Python	3.8+	Required for data processing services.
Docker	-	Recommended for containerized development.
Starknet Wallet	-	e.g., MetaMask or Argent, for blockchain integration.

Sources: README.md:66-71, ARCHITECTURE.md:130-134, apps/data-processing/setup.py:18

Initial Setup Flow

The following diagram illustrates the initial setup process for new contributors.

This flowchart shows the steps from forking the project to being ready for development.
Sources: CONTRIBUTING.md:19-25, README.md:74-81

1. Fork the Repository: Start by creating your own copy of the onchainsage repository on GitHub.
   Sources: CONTRIBUTING.md:20-21
2. Clone Your Fork: Clone your forked repository to your local machine.

   git clone https://github.com/your-username/onchainsage.git
   cd onchainsage
   

   Sources: CONTRIBUTING.md:23-25
3. Install Dependencies: The project uses npm workspaces. Install all dependencies from the root directory.

   npm install
   

   Sources: README.md:79-81
4. Environment Configuration: Create environment configuration files (e.g., .env) for each application in the apps/ directory. These are based on the example files provided in the docs/ folder or templates within each app's directory (like config/env.template in apps/dojo).
   Sources: README.md:83-84, apps/dojo/README.md:46-49, apps/backend/README.md:52-56

Project Structure and Development

OnChain Sage uses a monorepo structure to manage its different services. Each component is located in its own folder under apps/, and shared utilities are in packages/.

Sources: README.md:92-94

Monorepo Structure

The diagram below shows the high-level folder structure of the project.

This diagram visualizes the monorepo structure, separating applications, shared packages, and configuration.
Sources: README.md:96-107

Running Applications

Each service can be run locally using npm workspace commands from the project root.

Service	Command	Description
Frontend	npm run dev --workspace=apps/frontend	Starts the Next.js development server.
Backend	npm run start:dev --workspace=apps/backend	Starts the NestJS backend with hot-reloading.
Data Processing	pip install -e .	Installs the data processing package in editable mode.
Dojo (Starknet)	sozo build && sozo migrate	Builds and deploys the Starknet contracts to a local Katana node.

Sources: README.md:87-90, apps/frontend/README.md:15-17, apps/backend/README.md:59-61, apps/data-processing/README.md:42-44, apps/dojo/README.md:68-69

Contribution Workflow

To ensure code quality and a streamlined process, please follow the workflow outlined below for all contributions.

Sources: CONTRIBUTING.md:17-18

Pull Request (PR) Process

This sequence diagram shows the end-to-end process for submitting a pull request.

This diagram details the steps from creating a branch to getting a PR merged.
Sources: CONTRIBUTING.md:27-42

Branching and Commits

• Branching Strategy: All new features and bug fixes must be developed in a feature or bugfix branch created from the main branch. The main branch contains production-ready code.
  Sources: CONTRIBUTING.md:28-30, 43-45
• Commit Conventions: Follow the specified commit message conventions to maintain a clear and descriptive git history.
  • Feature: feat: [brief description]
  • Fix: fix: [brief description]
  • Docs: docs: [brief description]
    Sources: CONTRIBUTING.md:33-37

Code Standards & Testing

All contributions must adhere to the project's coding standards and include appropriate tests.

Sources: CONTRIBUTING.md:48-49

Formatting & Linting

The project uses linters and formatters to maintain code consistency. Run these tools before submitting a PR.

Service	Script	Description
Backend (NestJS)	npm run lint	Lints TypeScript files using ESLint.
Backend (NestJS)	npm run format	Formats TypeScript files using Prettier.
Dojo (Cairo)	./scripts/format.sh	Formats and lints Cairo code.
Data Processing (Python)	flake8 src/	Lints Python code using Flake8.

Sources: CONTRIBUTING.md:50, apps/backend/package.json:10,13, apps/dojo/README.md:80-82, apps/data-processing/README.md:51

Testing

Write unit and integration tests for your changes and ensure all existing tests pass.

Service	Script	Description
Frontend	npm test	Runs frontend tests.
Backend	npm run test	Runs unit tests with Jest.
Backend	npm run test:e2e	Runs end-to-end tests with Jest.
Data Processing	pytest tests/	Runs Python tests with Pytest.
Dojo (Starknet)	./scripts/test.sh	Runs all Dojo and Starknet Foundry tests.

Sources: CONTRIBUTING.md:51, ARCHITECTURE.md:139-144, apps/backend/README.md:70-72, apps/data-processing/README.md:48, apps/dojo/README.md:73-75

Documentation

Update the relevant documentation when making changes to code or adding new features. This is crucial for keeping the project maintainable and accessible to others.

Sources: CONTRIBUTING.md:52

Communication

• GitHub Issues & PRs: Use GitHub for all discussions, bug reports, and feature requests.
• Community Channels: Join the Telegram group for real-time discussions and support.

Sources: CONTRIBUTING.md:55-57

Your contributions are vital to the success of OnChain Sage. We appreciate your effort and commitment to building a robust, community-driven crypto trading tool.

Sources: CONTRIBUTING.md:62-63