Contribution Workflow

For repository organization and naming conventions, see Repository Structure. For Git branching strategy, see Branching & PR Conventions.

Getting Started

Prerequisites

Before contributing, ensure you have the following installed:

• Node.js: Version 20.0 or higher
• Git: Latest stable version
• npm: Included with Node.js

For complete system requirements, see Installation — Prerequisites.

Licensing

MiningOS is released under the Apache License 2.0. By contributing, you agree that your contributions will be licensed under the same terms. Key points:

• You retain copyright of your contributions
• You grant a perpetual, royalty-free license to use your contributions
• Contributions are provided "AS IS" without warranty

For license documentation requirements, see Code Documentation — License Section.

Development Environment Setup

1. Fork and Clone

1. Fork the repository on GitHub.

2. Clone your fork locally and navigate into the directory:

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

3. Add the upstream remote to sync with the main repository:

   git remote add upstream https://github.com/tetherto/REPOSITORY_NAME.git

For upstream synchronization procedures, see Branching Conventions — Upstream Synchronization.

2. Install Dependencies

1. Install all required Node.js packages:

   npm install

3. Configure the Worker

All MiningOS workers use a setup script to initialize configuration files.

1. Run the setup script to copy configuration templates to their working location:

   ./setup-config.sh

   This copies .example configuration files to working copies.

2. (Optional) Generate test-specific configuration files using the -t flag:

   ./setup-config.sh -t

For configuration file structure, see Repository Structure — Standard Directory Structure.

4. Configuration Files

Check out the Repository Structure chapter to learn which files to edit for configuring your worker. Key configuration files include:

5. Verify Setup

1. Start your worker in development mode with debug logging enabled:

   DEBUG="*" node worker.js --wtype WORKER_TYPE --env development --rack rack-0

2. Check the status of the running worker:

   cat status/WORKER_TYPE-rack-0.json

For complete installation examples, see Installation Guide.

Pull Request Workflow

Branch Naming Convention

Use descriptive branch names following the \{type\}/\{short-description\} pattern.

Types:

• feature/ — New features or workers
• fix/ — Bug fixes
• docs/ — Documentation changes
• refactor/ — Code refactoring
• test/ — Test additions or modifications

Examples

1. Create a new branch for a feature:

   git checkout -b feature/schneider-pm5350-worker

2. Create a new branch for a bug fix:

   git checkout -b fix/modbus-timeout-handling

3. Create a new branch for documentation:

   git checkout -b docs/api-reference-update

For detailed branching strategy, see Branching & PR Conventions.

Keeping Your Fork Updated

1. Fetch the latest changes from the main repository:

   git fetch upstream

2. Switch to your local main branch:

   git checkout main

3. Merge the upstream changes into your local branch:

   git merge upstream/main

4. Push the synchronized changes to your fork on GitHub:

   git push origin main

For automated upstream merging, see Branching Conventions — Upstream Synchronization.

Pull Request Steps

1. Create a feature branch from main
2. Make changes following Code Standards
3. Write/update tests (see Testing Guidelines
4. Run linting and tests
5. Commit with meaningful messages (see Branching Conventions — Commit Message Conventions)
6. Push and create pull request

PR Title Format

Use the convention \{type\}(\{scope\}): \{description\}.

Types: feat, fix, docs, refactor, test, chore

Examples:

• feat(miner): add Antminer S21 support
• fix(orchestrator): resolve action timeout handling
• docs(api): update listThings documentation

For complete PR guidelines, see Branching Conventions — Pull Request Workflow.

Code Standards

JavaScript Style

MiningOS uses Standard style. Key rules:

• 2-space indentation
• No semicolons
• Single quotes for strings
• Space after keywords (if, for, while)
• No unused variables

For complete linting guidelines, see Testing & Linting Guidelines — Linting with Standard.js.

Linting

1. Check your code for style violations:

   npm run lint

2. Automatically fix style issues where possible:

   npm run lint:fix

Naming Conventions

Error Handling

Use consistent error codes with the ERR_ prefix.

1. Throw an error for an invalid request parameter:

   if (!req.id) {
     throw new Error('ERR_THING_ID_INVALID')
   }

2. Throw an error when a requested resource is not found:

   if (!this.mem.things[req.id]) {
     throw new Error('ERR_THING_NOTFOUND')
   }

Standard error patterns:

For error documentation standards, see Code Documentation — Error Message Documentation.

RPC Method Implementation Pattern

Follow this structure for Remote Procedure Call (RPC) methods:

async myMethod(req) {
   // 1. Validate required parameters
   if (!req.param) {
      throw new Error('ERR_PARAM_INVALID')
   }

   // 2. Validate optional parameters with defaults
   const limit = req.limit || 100

   // 3. Business logic
   const result = await this.doSomething(req.param)

   // 4. Return result
   return result
}

Actual example from Orchestrator worker, file miningos-wrk-ork/workers/aggr.proc.ork.wrk.js:

async registerRack (req) {
   // 1. Validate required parameters
   if (!req.id) {
      throw new Error('ERR_RACK_ID_INVALID')
   }
   if (!req.type) {
      throw new Error('ERR_RACK_TYPE_INVALID')
   }
   const info = req.info
   if (!info.rpcPublicKey) {
      throw new Error('ERR_RACK_INFO_RPC_PUBKEY_INVALID')
   }
   // 3. Business logic
   await this.racks.put(req.id, Buffer.from(JSON.stringify(req)))
   // 4. Return result
   return 1
}

For RPC communication architecture, see Architecture — RPC Protocol. For function documentation, see Code Documentation — Function Documentation.

Debug Logging

1. Initialize a debug logger with a namespace:

   const debug = require('debug')('thing:proc')

2. Log informational messages, errors, and thing-specific errors within your methods:

   this.debug('operation started')
   this.debugError('context', error)
   this.debugThingError(thg, error)

Enable debug output when running your worker:

1. Enable logs for all thing modules:

   DEBUG="thing:*" node worker.js ...

2. Enable logs for all ork (orchestrator) modules:

   DEBUG="ork:*" node worker.js ...

3. Enable logs for all modules (verbose):

   DEBUG="*" node worker.js ...

For inline comment standards, see Code Documentation — Inline Comments.

Related Documentation

Contributor Guide

• Repository Structure — Code organization and naming conventions
• Branching & PR Conventions — Git workflow and commit messages
• Testing & Linting Guidelines — Test framework and code style
• Code Documentation Standards — JSDoc and documentation requirements
• Adding New Worker Type — Creating Level 4 and Level 5 workers

General Documentation

• Overview — What is MiningOS
• Architecture — System design and RPC communication
• Supported Devices — Hardware compatibility
• Installation — Complete setup instructions

Operator Manual

• Dashboard — Main monitoring interface
• Explorer — Device search and management
• Requests & Approvals — Action authorization workflow
• Alerts Manual — Alert types and error handling
• Settings — User management and permissions