Contributing Guide

We welcome contributions from the community! This comprehensive guide outlines the process for contributing to JuliaOS, whether you're fixing bugs, adding features, improving documentation, or helping with testing.

Ways to Contribute

Code Contributions

• Bug Fixes: Fix issues in the existing codebase

• Feature Development: Implement new features or enhancements

• Performance Improvements: Optimize existing code for better performance

• Test Coverage: Add or improve tests for existing functionality

Documentation Contributions

• Technical Documentation: Improve API references and technical guides

• Tutorials: Create step-by-step guides for common tasks

• Examples: Add example projects or code snippets

• Diagrams: Create visual explanations of system architecture or workflows

Community Support

• Issue Triage: Help categorize and reproduce reported issues

• Code Reviews: Review pull requests from other contributors

• Forum Support: Answer questions in community forums or discussions

• Translations: Help translate documentation into other languages

Getting Started

Setting Up Your Development Environment

Before you start contributing, you'll need to set up your development environment:

1. Prerequisites:

   • Git

   • Node.js (v16+)

   • npm (v7+)

   • Julia (v1.8+)

   • Python (v3.8+) for Python wrapper contributions

2. Fork the Repository:

   • Visit JuliaOS repository
   • Click the "Fork" button in the top-right corner

3. Clone Your Fork:

   git clone https://github.com/YOUR_USERNAME/JuliaOS.git
   cd JuliaOS

4. Set Up Upstream Remote:

   git remote add upstream https://github.com/Juliaoscode/JuliaOS.git

5. Install Dependencies:

   # Install Node.js dependencies
   npm install
   
   # Install Julia dependencies
   julia -e 'using Pkg; Pkg.activate("julia"); Pkg.instantiate()'
   
   # Install Python dependencies (if working on Python wrapper)
   pip install -e ./packages/python-wrapper

6. Verify Setup:

   # Run tests to verify your setup
   npm test
   cd julia && julia --project=. test/runtests.jl

Contribution Workflow

1. Find or Create an Issue

Before starting work, find an existing issue or create a new one:

• Browse Issues: Check GitHub Issues for existing tasks
• Create an Issue: If you found a bug or have a feature idea, create a new issue

• Discuss: For significant changes, discuss your approach in the issue before starting work

2. Create a Branch

Create a branch for your work using a descriptive name:

# Sync with upstream first
git fetch upstream
git checkout main
git merge upstream/main

# Create a new branch
git checkout -b TYPE/DESCRIPTION

Where:

• TYPE is one of: feature, fix, docs, test, refactor, perf, chore

• DESCRIPTION is a brief description of the change (e.g., feature/add-solana-wallet)

3. Make Your Changes

Implement your changes following these guidelines:

• Follow Code Style: Adhere to the project's coding conventions

• Keep Changes Focused: Address one concern per pull request

• Write Tests: Add tests for new features or bug fixes

• Update Documentation: Update relevant documentation for your changes

4. Test Your Changes

Ensure your changes work correctly and don't break existing functionality:

# Run TypeScript/JavaScript tests
npm test

# Run Julia tests
cd julia
julia --project=. test/runtests.jl

# Run Python tests (if applicable)
cd packages/python-wrapper
pytest

5. Format and Lint Your Code

Ensure your code follows the project's style guidelines:

# Format TypeScript/JavaScript code
npm run format

# Lint TypeScript/JavaScript code
npm run lint

# Check TypeScript types
npm run typecheck

6. Commit Your Changes

Write clear, descriptive commit messages following the Conventional Commits format:

git add .
git commit -m "type(scope): description"

Where:

• type is one of: feat, fix, docs, style, refactor, perf, test, chore

• scope is optional and indicates the part of the codebase affected (e.g., agents, swarms, cli)

• description is a concise description of the change

Examples:

• feat(agents): add support for custom agent parameters

• fix(bridge): resolve connection timeout issue

• docs(api): update wallet integration documentation

7. Push Your Changes

Push your branch to your fork:

git push origin your-branch-name

8. Create a Pull Request

1. Go to the JuliaOS repository
2. Click "Pull Requests" and then "New Pull Request"

3. Click "compare across forks"

4. Select your fork and branch

5. Fill out the pull request template with details about your changes

6. Click "Create Pull Request"

Pull Request Guidelines

PR Title and Description

• Title: Use the format type(scope): description (same as commit message)

• Description: Include the following sections:

  • Purpose: What does this PR do?

  • Related Issue: Link to the related issue (e.g., Fixes #123)

  • Changes: List of key changes made

  • Testing: How were the changes tested?

  • Screenshots: If applicable, add screenshots or GIFs

PR Checklist

Ensure your PR meets these requirements:

• Code follows the project's style guidelines

• Tests have been added or updated for changes

• Documentation has been updated if needed

• All tests pass

• Commits follow the conventional format

• PR is linked to an issue

Code Review Process

1. Initial Review: Maintainers will review your PR for basic requirements

2. Detailed Review: Code will be reviewed for correctness, style, and performance

3. Feedback: You may receive feedback requesting changes

4. Iteration: Address feedback and push additional commits

5. Approval: Once approved, a maintainer will merge your PR

Documentation Contributions

Documentation is crucial for JuliaOS. Here's how to contribute to documentation:

Documentation Structure

• /docs/gitbook/: Main documentation source for GitBook

  • /technical/: Technical documentation

  • /tutorials/: Step-by-step guides

  • /examples/: Example projects and code

Documentation Guidelines

• Clear Language: Use simple, clear language

• Code Examples: Include working code examples

• Structure: Use proper headings and lists for organization

• Completeness: Cover all aspects of the feature or API

• Consistency: Follow existing documentation style

Documentation Workflow

1. Find Documentation Needs: Identify missing or unclear documentation

2. Create a Branch: Follow the same branching strategy as code contributions

3. Make Changes: Update or add documentation files

4. Preview Changes: Use a Markdown previewer to check formatting

5. Submit PR: Follow the same PR process as code contributions

Testing Contributions

Improving test coverage is valuable. Here's how to contribute tests:

Types of Tests

• Unit Tests: Test individual functions and components

• Integration Tests: Test interactions between components

• End-to-End Tests: Test complete workflows

• Performance Tests: Measure and validate system performance

Testing Guidelines

• Test Coverage: Aim for high test coverage of critical code paths

• Test Organization: Group related tests together

• Test Independence: Tests should not depend on each other

• Test Clarity: Tests should clearly show what's being tested

Community Guidelines

Code of Conduct

All contributors must adhere to our Code of Conduct. We are committed to providing a welcoming and inclusive environment for everyone.

Communication Channels

• GitHub Issues: For bug reports and feature requests

• Pull Requests: For code and documentation contributions

• Discussions: For general questions and community discussions

Recognition

All contributors will be recognized in the project's contributors list. We value every contribution, whether it's code, documentation, tests, or community support.

Additional Resources

• Development Setup Guide: Detailed guide for setting up your development environment

• Testing & Debugging Guide: Guide for testing and debugging JuliaOS

• Best Practices: Coding standards and best practices

• Architecture Overview: Overview of the JuliaOS architecture

Questions?

If you have any questions about contributing, please open a discussion on GitHub or reach out to the maintainers. We're here to help!