Contribution Workflow

This guide outlines how to contribute to the MiningOS ecosystem, covering everything from setting up your development environment to submitting pull requests.

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:

File	Purpose	Documentation
config/common.json	Worker-wide settings	Repository Structure — Key Files
config/base.thing.json	Thing-specific configuration	Adding New Worker — Configuration
config/facs/net.config.json	Network/RPC configuration	Architecture — RPC Protocol

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

Element	Convention	Example	Documentation
Classes	PascalCase	WrkPowerMeterRack	Repository Structure — Class Names
Methods	camelCase	collectThingSnap	Adding New Worker — Abstract Methods
Constants	SCREAMING_SNAKE_CASE	RPC_METHODS	Code Documentation — Constants
Files (workers)	dot.separated.wrk.js	pm5340.rack.powermeter.wrk.js	Adding New Worker — Worker File Naming
Files (libs)	kebab-case.js	wrk-fun-stats.js	Repository Structure
Config keys	camelCase	collectSnapsItvMs	Adding New Worker — Configuration

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:

Error Code	Meaning	Related UI
ERR_*_INVALID	Invalid parameter value	Explorer
ERR_*_NOTFOUND	Resource not found	Alerts Manual
ERR_*_MISSING	Required field missing	—
ERR_SLAVE_BLOCK	Operation blocked on slave	Requests & Approvals
ERR_MISSING_WRITE_PERMISSIONS	Insufficient permissions	User Management

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