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 [email protected]:<your-username>/<repo-name>.git
cd <repo-name>

# Add upstream remote (parent repository)
git remote add upstream [email protected]:tetherto/<parent-repo>.git

# Verify remotes
git remote -v

# origin    <[email protected]>:<your-username>/<repo-name>.git (fetch)
# origin    <[email protected]>:<your-username>/<repo-name>.git (push)
# upstream  <[email protected]>:tetherto/<parent-repo>.git (fetch)
# upstream  <[email protected]>: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

1. Run linting (see Testing Guidelines — Linting):

   npm run lint
   
   # Or auto-fix issues
   
   npm run lint:fix

2. Run tests (see Testing Guidelines):

   npm test

3. Rebase on latest main — incorporate changes from main (conflicts may ensue):

   git fetch upstream
   git rebase upstream/main

4. 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

1. Automated Checks: Ensure linting and tests pass

2. Code Review: At least one approval required

3. Address Feedback: Resolve all review comments

4. 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:

1. Create PR in parent repo first

2. Wait for merge and release

3. Update dependency in child repo:

   npm update <parent-package>

4. Test integration in child repo (see Testing Guidelines — Test Inheritance)

5. 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:

1. Contributor creates feature/fix branch from main

2. Contributor runs tests on the branch

3. If tests fail, Contributor fixes issues and returns to step 2

4. Contributor creates Pull Request targeting main

5. Reviewer performs code review

6. If changes requested, Contributor addresses feedback, pushes fixes, and returns to step 2

7. If rejected, Reviewer closes PR and process ends

8. If approved, Reviewer merges branch into main

9. Reviewer tags the release with version number (if applicable)

10. Reviewer deploys to production

11. If deployment fails, Reviewer rolls back to previous tag and returns to step 3

12. 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

---