Branching & PR Conventions

This document outlines the branching strategy, pull request workflow, and contribution guidelines for MiningOS repositories.

For development environment setup, see Contribution Workflow. For repository organization, see Repository Structure.

Branching Strategy

MiningOS follows a simplified Git Flow model with main as the single permanent branch.

Branch Paradigm

Branch	Purpose	Merges From	Merges To
main	Production-ready, deployed code	`feature/`, `fix/`, `hotfix/*`	—

Branch Types

Branch Type	Pattern	Purpose	Lifetime
main	`main`	Production-ready code	Permanent
feature	`feature/<description>`	New functionality	Temporary
fix	`fix/<description>`	Bug fixes	Temporary
hotfix	`hotfix/<description>`	Critical production fixes	Temporary
docs	`docs/<description>`	Documentation updates	Temporary
refactor	`refactor/<description>`	Code restructuring	Temporary

Branch Naming Conventions

Use lowercase with hyphens for readability:

# Good examples
feature/modbus-tcp-support
fix/rtd-collection-timeout
hotfix/hyperbee-connection-leak
docs/api-reference-update
refactor/stats-aggregation

# Bad examples
Feature/ModbusTCPSupport    # Wrong case
fix_rtd_timeout             # Underscores instead of hyphens
bugfix                      # Not descriptive

For naming conventions in code, see Contribution Workflow — Naming Conventions.

Branch Lifecycle

Diagram Explanation:

Feature and fix branches are created from main
Completed work merges back into main after PR approval
main represents production-ready code at all times
Releases are tagged directly on main after significant merges

Repository Setup

MiningOS uses a fork-based workflow with upstream remotes for synchronization with parent repositories. For the repository hierarchy, see Repository Structure — Repository Hierarchy.

Initial Setup

# Clone your fork
git clone git@github.com:<your-username>/<repo-name>.git
cd <repo-name>

# Add upstream remote (parent repository)
git remote add upstream git@github.com:tetherto/<parent-repo>.git

# Verify remotes
git remote -v

# origin    <git@github.com>:<your-username>/<repo-name>.git (fetch)
# origin    <git@github.com>:<your-username>/<repo-name>.git (push)
# upstream  <git@github.com>:tetherto/<parent-repo>.git (fetch)
# upstream  <git@github.com>:tetherto/<parent-repo>.git (push)

Upstream Synchronization

Keep your fork synchronized with upstream changes:

# Fetch upstream changes
git fetch upstream

# Sync main branch
git checkout main
git merge upstream/main

# Push to your fork
git push origin main

A convenience script (upstream-merge.sh) is provided in most repositories:

# !/bin/bash
git fetch upstream
git merge upstream/main

For directory structure including this script, see Repository Structure — Standard Directory Structure.

Creating a Feature Branch

Workflow

# Ensure main is up-to-date
git checkout main
git pull origin main
git fetch upstream
git merge upstream/main

# Create feature branch from main
git checkout -b feature/your-feature-name

# Make changes and commit
git add .
git commit -m "feat: add your feature description"

# Push to your fork
git push origin feature/your-feature-name

# Create PR targeting 'main' branch

Commit Message Conventions

MiningOS follows Conventional Commits specification.

Commit Format

<type>(<scope>): <subject>

[optional body]

[optional footer]

Commit Types

Type	Description	Example
`feat`	New feature	`feat(rpc): add getThingStats method`
`fix`	Bug fix	`fix(modbus): resolve connection timeout`
`docs`	Documentation	`docs(readme): update installation steps`
`style`	Code style (formatting)	`style: fix indentation in worker.js`
`refactor`	Code restructuring	`refactor(stats): simplify aggregation logic`
`perf`	Performance improvement	`perf(rtd): batch RTD writes to Hyperbee`
`test`	Adding/fixing tests	`test(rpc): add unit tests for listThings`
`chore`	Maintenance tasks	`chore: update dependencies`

Scope Examples

Scope should reflect the component or module affected:

Scope	Description	Related Documentation
`rpc`	RPC method changes	Architecture — RPC Protocol
`config`	Configuration changes	Repository Structure — Key Files
`modbus`	Modbus communication	Adding New Worker — Protocol Facilities
`stats`	Statistics/aggregation	Dashboard
`store`	Hyperbee storage	Architecture — Data Persistence
`worker`	Worker lifecycle	Repository Structure — Worker Implementation

Commit Examples

# Feature commit
git commit -m "feat(rpc): add bulkUpdateThings method for batch operations"

# Bug fix with issue reference
git commit -m "fix(modbus): handle connection reset on network timeout

Closes #42"

# Breaking change
git commit -m "feat(api)!: change listThings response format

BREAKING CHANGE: listThings now returns paginated results.
Previous format: { things: [...] }
New format: { things: [...], pagination: { ... } }"

Pull Request Workflow

Before Creating a PR

Run linting (see Testing Guidelines — Linting):

npm run lint

# Or auto-fix issues

npm run lint:fix

Run tests (see Testing Guidelines:
```
npm test
```
Rebase on latest main — incorporate changes from main (conflicts may ensue):
```
git fetch upstream
git rebase upstream/main
```
Squash commits — condense branch into shorter sequence of larger commits:
```
git rebase -i HEAD~<number-of-commits>
```

PR Title Format

Follow the same convention as commits:

<type>(<scope>): <description>

Examples:

feat(rpc): add getContainerStats method
fix(worker): resolve memory leak in RTD collection
docs(api): document all RPC methods

PR Description Template

## Description
Brief description of the changes.

## Type of Change
- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to change)
- [ ] Documentation update

## Changes Made
- Change 1
- Change 2
- Change 3

## Testing
Describe testing performed:
- [ ] Unit tests pass (`npm test`)
- [ ] Linting passes (`npm run lint`)
- [ ] Manual testing performed

## Related Issues
Closes #<issue-number>

## Checklist
- [ ] Code follows project style guidelines (Standard.js)
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated (if applicable)
- [ ] No new warnings introduced

For code style guidelines, see Contribution Workflow — Code Standards. For documentation requirements, see Code Documentation Standards.

PR Review Process

Automated Checks: Ensure linting and tests pass
Code Review: At least one approval required
Address Feedback: Resolve all review comments
Squash and Merge: Maintain clean commit history

Handling Upstream Inheritance

MiningOS workers inherit from base classes across repositories (see Repository Structure — Repository Hierarchy). When changes are needed in a parent repository:

Create PR in parent repo first
Wait for merge and release
Update dependency in child repo:
```
npm update <parent-package>
```
Test integration in child repo (see Testing Guidelines — Test Inheritance)
Create PR in child repo referencing parent changes

For creating new workers in the hierarchy, see Adding New Worker Type.

Release Process

Release Workflow

Releases are created by merging feature/fix branches into main and tagging, as described in the steps below:

Process steps:

Contributor creates feature/fix branch from main
Contributor runs tests on the branch
If tests fail, Contributor fixes issues and returns to step 2
Contributor creates Pull Request targeting main
Reviewer performs code review
If changes requested, Contributor addresses feedback, pushes fixes, and returns to step 2
If rejected, Reviewer closes PR and process ends
If approved, Reviewer merges branch into main
Reviewer tags the release with version number (if applicable)
Reviewer deploys to production
If deployment fails, Reviewer rolls back to previous tag and returns to step 3
Process ends successfully

The BPMN diagram below illustrates the workflow:

Version Tagging

# After merging to main, tag a release
git checkout main
git pull origin main

# Tag a release
git tag -a v1.2.0 -m "Release v1.2.0: Add RTD support"

# Push main and tags
git push origin main
git push origin v1.2.0

Versioning

MiningOS follows Semantic Versioning:

MAJOR (1.x.x): Breaking API changes
MINOR (x.1.x): New features, backward compatible
PATCH (x.x.1): Bug fixes, backward compatible

Quick Reference

Common Git Commands

# Start new feature (from main)
git checkout main && git pull && git checkout -b feature/my-feature

# Sync with upstream
git fetch upstream && git merge upstream/main

# Prepare for PR
npm run lint:fix && npm test

# Squash last N commits
git rebase -i HEAD~N

# Amend last commit
git commit --amend

# Force push after rebase (feature branch only!)
git push --force-with-lease origin feature/my-feature

PR Checklist

Branch from latest main
Follow commit message conventions
Run npm run lint — no errors (see Testing Guidelines)
Run npm test — all tests pass (see Testing Guidelines
Update documentation if needed (see Code Documentation Standards
PR targets main
Request review from maintainer

Branching & PR Conventions

On this page