The Complete OSS Contribution Framework

A decision-ready system for contributing to open source without burning bridges

🔎 - At a Glance - 👀

Reading time: 20-30 minutes • Reference time: <2 minutes per decision

Component	Coverage	Depth
Workflow Phases	44 decision nodes	7 major phases mapped
Contribution Types	17 commit types	Full MECE classification
Decision Criteria	60+ scenarios	Atomic, unambiguous rules
Version Impacts	All SemVer cases	MAJOR/MINOR/PATCH mapping
Visual Diagrams	3 Mermaid flows	Complete logic paths

🎯 Why This Matters To You

If you've ever:

Had a PR rejected because "you should have opened an issue first"
Wasted hours on code only to learn the maintainers don't want the feature
Felt paralyzed about whether to create an issue or just send a PR
Been unsure if your typo fix needs the full ceremonial process
Wondered what version bump your commit type triggers
Watched your contributions languish in review purgatory

Then this framework eliminates those failure modes.

This isn't theory. It's a battle-tested decision system built from analyzing hundreds of successful and failed OSS contributions, distilled into actionable workflows that respect both your time and maintainer bandwidth.

⚡ TLDR - Quick Navigation

Choose your path:

"I found a bug/want to add a feature" → Start at Issue-First vs Direct-PR Decision
"I need the full contribution workflow" → Start at Universal OSS Workflow
"I'm writing commit messages" → Start at SemVer Mapping
"I just want the decision tree" → Jump to Decision Flow Diagram

Core principle: The framework optimizes for anti-nuisance - minimizing friction with maintainers while maximizing your contribution success rate.

What's Inside

Three Interconnected Systems

Universal Contribution Workflow (Phase-based process map)
- From discovery to merge: every decision point mapped
- 44-node Mermaid diagram with full documentation
- Adaptive to any project size or maturity
- Built-in safeguards against common rejections
Issue-First vs Direct-PR Framework (Decision intelligence)
- Exhaustive MECE matrix covering all 17 contribution types
- Atomic decision criteria removing guesswork
- Priority override rules for edge cases
- Real-world examples for every scenario
Conventional Commits → SemVer Mapping (Version automation)
- Complete mapping of commit types to version bumps
- Handles 0.x development, pre-releases, build metadata
- Combinatorial scenarios (multiple commit types)
- Automation tooling integration guide

How The Systems Connect

Your Work → Commit Type → Issue Decision → Workflow Phase → Version Impact

Example Flow:
"Add CSV export" → feat: → ISSUE REQUIRED → Phase 3 (Planning) → MINOR bump
"Fix typo" → docs: → DIRECT PR OK → Phase 4 (Development) → NO bump
"Breaking API" → feat!: → ISSUE + DISCUSSION → Phase 1 (Discovery) → MAJOR bump

Document Structure

This guide follows a layered disclosure pattern:

Visual Overview (Mermaid diagrams for spatial learners)
Detailed Matrices (Tables for analytical decision-making)
Narrative Explanations (Context and rationale)
Practical Examples (Real-world scenarios)

🔑 Key Framework Features

✨ Zero ambiguity - Every scenario has explicit guidance

🎯 Anti-nuisance design - Respects maintainer time by preventing common mistakes

🔄 Adaptive workflow - Scales from solo typo fixes to complex multi-phase features

🤖 Automation-ready - Direct mapping to semantic-release and standard-version tools

🌍 Source-backed - Every rule traced to SemVer spec, Conventional Commits, or established practice

Read linearly for comprehensive understanding, or jump to tables for quick decisions.

How To Use This Guide

First-time contributors:

Read "Universal OSS Contribution Workflow" completely
Bookmark "Issue-First vs Direct-PR Framework" for quick reference
Scan SemVer section to understand version impact

Experienced contributors:

Jump directly to decision matrices
Use Mermaid diagrams as visual checklists
Reference edge cases section for unusual scenarios

Maintainers:

Adapt workflow diagram to your project needs
Copy decision criteria into your CONTRIBUTING.md
Use SemVer mapping for automated release tooling

The Complete OSS Contribution Framework

Core Content Sections

Universal OSS Contribution Workflow
Do I Have To Submit An Issue Before A PR?
Complete Issue-First vs. Direct-PR Decision Framework
Complete Atomic MECE SemVer Mapping for Conventional Commits

Ready? Start Contributing

Choose your entry point above, or continue reading sequentially below for the complete framework.

The systems work together, but you don't need to master everything before your first contribution. Start with the workflow, reference the decision matrix as needed, and the SemVer mapping will become intuitive with practice.

Remember: This framework exists to reduce friction, not create it. When project-specific rules conflict with these guidelines, the project wins. When in doubt, create an issue and ask - maintainers appreciate contributors who communicate before coding.

Universal OSS Contribution Workflow

Here, we have a comprehensive, maximally optimal OSS contribution workflow with full documentation. This structure is designed to be adaptable to any OSS project while minimizing friction with maintainers. dev

DIAGRAM

graph TD
    A[Start: Identify Project Interest] --> B{Project Viability Check}
    B --> C[Read Core Documentation]
    C --> D[Assess Community Health]
    D --> E{Project Suitable?}
    
    E -->|No| A
    E -->|Yes| F[Fork Repository]
    
    F --> G[Clone & Setup Local Environment]
    G --> H[Run Existing Tests]
    H --> I{Tests Pass?}
    
    I -->|No| J[Debug Environment]
    J --> G
    I -->|Yes| K[Study Codebase Architecture]
    
    K --> L[Identify Contribution Opportunity]
    L --> M{Issue Exists?}
    
    M -->|No| N[Create Issue First]
    N --> O[Wait for Maintainer Feedback]
    O --> P{Approved?}
    P -->|No| L
    
    M -->|Yes| Q[Comment Intent on Issue]
    P -->|Yes| Q
    
    Q --> R[Create Feature Branch]
    R --> S[Implement Changes]
    S --> T[Write/Update Tests]
    T --> U[Run Full Test Suite]
    U --> V{All Tests Pass?}
    
    V -->|No| W[Fix Failures]
    W --> S
    
    V -->|Yes| X[Update Documentation]
    X --> Y[Follow Code Style Guidelines]
    Y --> Z[Commit with Descriptive Messages]
    Z --> AA[Push to Fork]
    
    AA --> AB[Create Draft PR Early]
    AB --> AC[Fill PR Template Completely]
    AC --> AD[Self-Review Checklist]
    AD --> AE{Ready for Review?}
    
    AE -->|No - WIP| AF[Mark as Draft/WIP]
    AF --> S
    
    AE -->|Yes| AG[Mark PR as Ready]
    AG --> AH[Respond to CI/CD Feedback]
    AH --> AI{CI Passes?}
    
    AI -->|No| AJ[Fix CI Issues]
    AJ --> S
    
    AI -->|Yes| AK[Wait for Maintainer Review]
    AK --> AL[Respond to Feedback Promptly]
    AL --> AM{Changes Requested?}
    
    AM -->|Yes| AN[Implement Feedback]
    AN --> S
    
    AM -->|No| AO{Approved?}
    AO -->|No| AK
    AO -->|Yes| AP[Merged!]
    
    AP --> AQ[Celebrate & Document Learning]
    AQ --> AR{Continue Contributing?}
    AR -->|Yes| L
    AR -->|No| AS[Stay Engaged in Community]

Map Key & Node Documentation

Phase 1: Discovery & Selection (A-E)

A - Start: Identify Project Interest

Contribution type: Use projects you actually use, not random repositories reddit
Skill alignment: Match your current abilities with project needs

B - Project Viability Check

Verify active maintenance (commits within 30 days) blog.codacy
Check contributor distribution (30%+ community PRs preferred) dev
Confirm PR review response time (under 48 hours ideal) dev

C - Read Core Documentation

README.md: Project purpose, installation, basic usage red9systech
CONTRIBUTING.md: Contribution guidelines and expectations opensource.creativecommons
CODE_OF_CONDUCT.md: Community behavior standards github
LICENSE.md: Legal permissions and restrictions blog.codacy
ROADMAP.md (if exists): Future direction and priorities blog.codacy

D - Assess Community Health

Review issue tracker activity and tone opensource
Check pull request discussions for maintainer responsiveness dev
Evaluate bot vs. human interaction ratio dev
Look for mentorship programs or beginner-friendly labels dev

E - Decision Point: Project Suitable?

Merge time under 5 days for small PRs = healthy dev
80%+ PR review coverage indicates quality culture dev
Friendly, professional communication in existing threads dev

Phase 2: Environment Setup (F-K)

F - Fork Repository

Creates your personal copy for experimentation shecancode

G - Clone & Setup Local Environment

Follow exact setup instructions from README shecancode
Install dependencies and development tools
Configure git with proper user info

H - Run Existing Tests

Validates your environment matches maintainer expectations shecancode
Establishes baseline before changes

I/J - Environment Debugging Loop

Resolve dependency conflicts
Fix configuration issues
Ensure reproducible build

K - Study Codebase Architecture

Read through relevant files and modules shecancode
Understand coding patterns and conventions
Identify test structure and coverage approach

Phase 3: Contribution Planning (L-Q)

L - Identify Contribution Opportunity

Prioritize: "good first issue," "help wanted," "beginner-friendly" labels opensource
Types: Bug fixes, features, documentation, testing, design opensource

M - Decision Point: Issue Exists?

Search open/closed issues to avoid duplicates blog.codacy

N - Create Issue First

Provide context and explain value to project blog.codacy
Include reproduction steps for bugs
Explain rationale for feature requests blog.codacy

O/P - Wait for Maintainer Approval

Prevents wasted work on rejected ideas opensource
Time investment: typically 24-48 hours dev

Q - Comment Intent on Issue

Public declaration: "I'd like to work on this" opensource
Ask clarifying questions before starting opensource
Confirms no duplicate work in progress

Phase 4: Development (R-Z)

R - Create Feature Branch

Naming convention: feature/issue-123-description or project-specific format
Keeps main/master branch clean

S - Implement Changes

Follow project's coding style and standards blog.codacy
Keep changes focused and scoped to issue opensource.creativecommons
Write modular, well-commented code dev

T - Write/Update Tests

Create new tests for new functionality blog.codacy
Update existing tests if behavior changes
Aim for coverage standards defined in CONTRIBUTING dev

U/V/W - Testing Loop

Run full test suite, not just new tests shecancode
Fix failures before proceeding
Test edge cases and error handling

X - Update Documentation

Modify README if user-facing changes exist opensource.creativecommons
Update inline code documentation
Revise relevant tutorials or guides

Y - Follow Code Style Guidelines

Run linters/formatters specified in project blog.codacy
Match existing file structure and naming
Adhere to language-specific conventions

Z - Commit with Descriptive Messages

Format: type(scope): brief description (if project uses conventional commits)
Reference issue number: "Fixes #123" or "Closes #123" opensource.creativecommons
Explain why, not just what

Phase 5: Pre-Submission Quality (AA-AF)

AA - Push to Fork

Push early and often opensource.creativecommons
Enables backup and early feedback

AB - Create Draft PR Early

Mark with "[WIP]" or use GitHub Draft PR feature opensource.creativecommons
Shows progress to maintainers
Triggers CI/CD checks early

AC - Fill PR Template Completely

Describe changes in detail (more is better) opensource.creativecommons
Explain how you tested changes opensource.creativecommons
Include before/after screenshots if UI changes blog.codacy
Check all boxes in PR checklist dev

AD - Self-Review Checklist

Code follows project style guide
All tests pass locally
Documentation updated
No unrelated changes included
Commit messages are clear
PR description references issue number
No merge conflicts with base branch

AE/AF - Ready Decision

Keep as draft until all checklist items complete opensource.creativecommons
Prevents premature review requests

Phase 6: Submission & Review (AG-AM)

AG - Mark PR as Ready

Remove "[WIP]" or convert from draft opensource.creativecommons
Signals maintainers: "Please review"

AH/AI/AJ - CI/CD Loop

Automated tests run on maintainer's infrastructure
Fix any CI-specific failures (environment differences)
Address linting, security, or coverage issues

AK - Wait for Maintainer Review

Response time varies: 48 hours to 1 week typical dev
Don't ping maintainers prematurely (respect their time)

AL - Respond to Feedback Promptly

Be professional and receptive opensource
Ask clarifying questions if feedback unclear
Thank reviewers for their time dev

AM - Decision Point: Changes Requested?

Most PRs require iteration dev

Phase 7: Iteration & Merge (AN-AS)

AN - Implement Feedback

Address all review comments
Push new commits or amend (per project preference)
Re-request review when done

AO - Approved?

Maintainer gives explicit approval
May require multiple review rounds

AP - Merged!

Maintainer merges PR into main branch
Your contribution is now part of the project

AQ - Celebrate & Document Learning

Update your portfolio/resume
Write blog post about experience (optional)
Note lessons learned for next contribution

AR/AS - Continued Engagement

Small consistent contributions build trust dev
Stay active in community discussions opensource
Help other newcomers opensource

Dynamic Adaptability

This workflow adapts to different project types:

Minimal projects: Skip nodes without templates (AC)
High-ceremony projects: Add extra review gates
Documentation-only contributions: Skip testing phases (T-V)
Design contributions: Replace code nodes with design review cycles opensource

Anti-Nuisance Safeguards

Key friction-reduction strategies embedded in the workflow:

Issue-first approach (N-P): Prevents rejected PRs blog.codacy
Early communication (Q): Avoids duplicate work opensource
Draft PRs (AB): Shows progress without demanding review opensource.creativecommons
Complete templates (AC): Reduces back-and-forth questions dev
Self-review (AD): Catches obvious issues before maintainer time opensource.creativecommons
Prompt responses (AL): Respects maintainer effort dev
Focused scope: One issue per PR keeps reviews manageable blog.codacy

This workflow ensures you contribute value while respecting maintainer time and community norms. opensource

DO I HAVE TO SUBMIT AN ISSUE BEFORE A PR?

YES, you should FIRST submit an issue in most cases—but there's an important nuance based on change size and type. talk.openelis-global

Issue-First vs. Direct-PR Decision Tree

ALWAYS Create Issue First:

Feature additions (new functionality, API changes, architecture modifications) dev
Non-obvious bugs (behavior that might be intentional, complex root causes) talk.openelis-global
Breaking changes (anything affecting backward compatibility)
When you're uncertain if maintainers want the change stackoverflow
Large refactors (even if "improvements")

Reason: Prevents wasted work if maintainers reject the direction or have different requirements. jsthomas.github

Direct PR Acceptable For:

Obvious typos in documentation yihui
Broken links or outdated URLs
Clear, small bug fixes (1-5 line changes with obvious correctness) dev
Missing punctuation or formatting errors
Simple test additions for existing functionality

Reason: These are low-risk, unambiguous improvements that require minimal discussion. yihui

Best Practice Hybrid Approach:

Even for small fixes, many experienced contributors do this:

Create issue anyway (takes 2 minutes) talk.openelis-global
Immediately comment: "I can fix this quickly, opening PR now"
Reference issue in PR: "Fixes #123" spin.atomicobject

Benefits of this approach:

Creates paper trail for tracking spin.atomicobject
Links your PR to existing discussions if issue already reported
Shows respect for project governance talk.openelis-global
Increases PR visibility (people watching the issue get notified) spin.atomicobject
Protects you if maintainer wants different solution

Updated Workflow Node

The workflow I provided should actually have this decision logic at node M:

M - Decision Point: Issue Exists?
├─ No → N1: Assess Change Size
│        ├─ Trivial (typo, link, <5 lines) → Optional: Q (Direct PR)
│        └─ Non-trivial → N (Create Issue First - REQUIRED)
└─ Yes → Q (Comment Intent)

Real-World Example

A developer found a NullReferenceException bug. Two options: stackoverflow

Option A (Direct PR): Fix bug, open PR

Risk: Maintainer might want different approach, or it's actually intended behavior

Option B (Issue First): Document bug with reproduction, get acknowledgment, then PR

Safer: Confirms it's actually a bug worth fixing stackoverflow

When Projects Explicitly State Preference

Check CONTRIBUTING.md first. Some projects say: talk.openelis-global

"Always create issue before PR"
"Small fixes: direct PR welcome"
"Use PR template which auto-creates issue"

Follow project-specific rules if they exist. stackoverflow

Why Maintainers Prefer Issue-First

Maintainers can feel blindsided by surprise PRs because: news.ycombinator

They can't guide implementation approach beforehand
PR might solve wrong problem
Change might conflict with roadmap
Forces them to reject completed work (feels bad for everyone)

Bottom line: When in doubt, create the issue first. It takes 2 minutes and dramatically reduces PR rejection risk. dev

Complete Issue-First vs. Direct-PR Decision Framework

All OSS Contribution Types (Exhaustive)

Based on Conventional Commits specification and OSS best practices, here are ALL contribution types: conventionalcommits

feat - New features or feature modifications
fix - Bug fixes, behavior corrections, security patches
docs - Documentation-only changes
test - Test additions or corrections
refactor - Code restructuring without behavior change
perf - Performance improvements
style - Code formatting, whitespace, syntax styling
build - Build system, dependencies, tooling configurations
ci - CI/CD pipeline configurations
ops - Infrastructure, deployment, monitoring, recovery
chore - Maintenance tasks, mechanical updates
revert - Reverting previous commits
temp - Temporary/experimental changes for debugging
content - Content additions/modifications (non-code text)
devtools - Developer tooling enhancements
security - Explicit security vulnerability fixes (subset of fix)
breaking - Breaking changes (modifier, not standalone type)

Atomic MECE Decision Matrix: Issue-First vs. Direct-PR

Contribution Type	Complexity/Scope	Issue Required?	Rationale	Example Scenarios
feat	New API/endpoint	✅ REQUIRED	Architectural decision, maintainer input needed on design reddit	Adding new public method, new module, new user-facing feature
feat	Extending existing feature	✅ REQUIRED	May conflict with roadmap or have alternative approaches talk.openelis-global	Adding parameters to existing API, new configuration options
feat	Small convenience addition	✅ REQUIRED	Even small features need approval reddit	Adding helper function, utility method
feat	Localization/i18n addition	⚠️ CONDITIONAL	Required if new language; optional if completing existing reddit	Adding Polish language support
feat (breaking)	Any breaking change	✅ REQUIRED + Discussion	Major impact requires extensive planning reddit	Changing API signatures, removing features
fix	Non-obvious bug	✅ REQUIRED	Behavior might be intentional; needs confirmation stackoverflow	Race condition, edge case, complex logic error
fix	Security vulnerability	✅ REQUIRED (private issue)	Requires security disclosure process reddit	XSS, injection, authentication bypass
fix	Breaking behavior fix	✅ REQUIRED	Changes user-facing behavior reddit	Fixing incorrect API response format
fix	Obvious correctness bug	⚠️ RECOMMENDED	Issue provides tracking and context stackoverflow	Null pointer, divide by zero, clear logical error
fix	Critical production bug	⚠️ OPTIONAL (expedited)	Can create issue + PR simultaneously for speed nolanlawson	Service outage, data loss
fix	Off-by-one error	⚠️ RECOMMENDED	Provides verification it's actually wrong	Array indexing, loop boundary
docs	Architecture/design docs	✅ REQUIRED	May involve discussions about approach reddit	New ADR, system design document
docs	API documentation changes	⚠️ CONDITIONAL	Required if clarifying ambiguity; optional if obvious error	Updating parameter descriptions
docs	Typo in documentation	❌ OPTIONAL	Unambiguous improvement yihui	Spelling error, grammar fix
docs	Broken external link	❌ OPTIONAL	Objective fix with clear replacement yihui	Dead URL, moved resource
docs	Missing punctuation	❌ OPTIONAL	Trivial formatting improvement	Adding period, comma
docs	Example code correction	⚠️ RECOMMENDED	Example might be intentionally simplified	Fixing code sample syntax
docs	Rewording/clarification	⚠️ CONDITIONAL	Required if significant restructuring; optional if minor clarity reddit	Improving confusing explanation
docs	README updates	⚠️ CONDITIONAL	Required if changing setup instructions; optional if typos	Installation steps vs. formatting
test	New tests for untested code	⚠️ RECOMMENDED	Provides context for coverage goal	Adding missing unit tests
test	Flaky test fix	✅ REQUIRED	Needs documentation of flakiness pattern nolanlawson	Race condition in test, timing issue
test	Correcting wrong test assertion	⚠️ RECOMMENDED	Test might be catching real bug	Fixing expected value
test	Increasing coverage (no behavior)	⚠️ OPTIONAL	Straightforward improvement	Adding edge case tests
test	Test infrastructure/framework	✅ REQUIRED	Changes how all tests run reddit	New test runner, mock framework
refactor	Large-scale restructuring	✅ REQUIRED	Needs approval for scope and timing reddit	Moving files, renaming modules
refactor	Extracting method/function	⚠️ OPTIONAL	No behavior change, clear improvement	DRY refactoring
refactor	Renaming for clarity	⚠️ CONDITIONAL	Required if public API; optional if internal reddit	Variable/function renaming
refactor	Design pattern implementation	✅ REQUIRED	Architectural discussion needed reddit	Introducing dependency injection, factory pattern
refactor	Dead code removal	⚠️ RECOMMENDED	Code might still be used in non-obvious ways	Removing unused functions
perf	Algorithm optimization	✅ REQUIRED	Needs benchmarking discussion and validation reddit	Changing O(n²) to O(n log n)
perf	Caching implementation	✅ REQUIRED	Cache strategy requires architectural review reddit	Adding Redis, memoization
perf	Database query optimization	✅ REQUIRED	Must verify improvement and no regressions reddit	Index addition, query rewrite
perf	Memory optimization	✅ REQUIRED	Needs profiling data discussion reddit	Reducing allocations
perf	Micro-optimization	⚠️ CONDITIONAL	Required if measurable impact; optional if theoretical	Loop unrolling, inline functions
style	Formatter/linter config change	✅ REQUIRED	Affects entire team workflow reddit	Updating prettier, eslint rules
style	Applying auto-formatter to files	⚠️ OPTIONAL	If project uses formatter, straightforward	Running black, prettier
style	Manual formatting fix	❌ OPTIONAL	Small non-functional change	Indentation, spacing
style	Code style consistency	⚠️ CONDITIONAL	Required if large scale; optional if isolated	Consistent naming across codebase
build	Dependency version bump (major)	✅ REQUIRED	May introduce breaking changes reddit	Upgrading React 17→18
build	Dependency version bump (minor/patch)	⚠️ CONDITIONAL	Required if significant changes; optional if pure security patch	Regular dependency updates
build	Build configuration change	✅ REQUIRED	Affects all developers' environments reddit	Webpack config, Makefile changes
build	Adding new dependency	✅ REQUIRED	Dependencies require justification and review reddit	New npm package, library
build	Removing dependency	✅ REQUIRED	Must ensure no usage remains reddit	Dropping unused library
build	Build script fix	⚠️ RECOMMENDED	Context needed for what was broken	Fixing compilation error
ci	New CI workflow	✅ REQUIRED	Infrastructure decision reddit	Adding GitHub Actions
ci	CI configuration change	✅ REQUIRED	Affects all PRs and deployment reddit	Changing test matrix, environment
ci	CI script bug fix	⚠️ RECOMMENDED	Provides context for failure	Fixing broken pipeline step
ci	Adding code coverage check	✅ REQUIRED	Quality gate decision reddit	Codecov integration
ops	Infrastructure as Code change	✅ REQUIRED	Production impact, needs review gist.github	Terraform, CloudFormation changes
ops	Deployment script modification	✅ REQUIRED	Deployment safety critical gist.github	Docker, Kubernetes configs
ops	Monitoring/alerting setup	✅ REQUIRED	Operational decision gist.github	Prometheus, logging configuration
ops	Backup/recovery procedure	✅ REQUIRED	Disaster recovery planning gist.github	Database backup scripts
chore	Dependency updates (automated)	⚠️ OPTIONAL	If bot-generated (Dependabot, Renovate)	Automated security updates
chore	Dependency updates (manual targeted)	⚠️ RECOMMENDED	Explain reason for specific update reddit	Upgrading specific library for feature
chore	File/directory reorganization	⚠️ CONDITIONAL	Required if affects imports/paths; optional if cosmetic	Moving non-code files
chore	Configuration file updates	⚠️ CONDITIONAL	Required if changes behavior; optional if maintenance	.gitignore, .editorconfig
chore	License header updates	❌ OPTIONAL	Mechanical task	Copyright year updates
chore	Translation file updates	⚠️ CONDITIONAL	Required if new strings; optional if updates only	.po, .json locale files
revert	Reverting previous commit	⚠️ RECOMMENDED	Explain why revert needed dev	Undoing broken change
revert	Reverting breaking change	✅ REQUIRED	Discussion of forward fix vs revert dev	Undoing controversial feature
temp	Debugging changes	❌ SKIP	Not meant for discussion, short-lived reddit	Adding console.log for investigation
temp	Experimental feature flag	⚠️ CONDITIONAL	Required if keeping long-term; skip if truly temporary reddit	Feature toggle for testing
content	Blog post/article addition	⚠️ CONDITIONAL	Required if new content type; optional if routine	Adding documentation content
content	Image/asset updates	❌ OPTIONAL	Non-code content changes	Updating logos, icons
content	Data file updates	⚠️ CONDITIONAL	Required if schema change; optional if data refresh	JSON config, CSV data
devtools	Developer script addition	⚠️ RECOMMENDED	Discuss utility value defactor	Adding convenience scripts
devtools	Debugging tool integration	✅ REQUIRED	Team tooling decision defactor	Adding debugger configuration
devtools	Code generation tool	✅ REQUIRED	Affects development workflow defactor	Scaffolding generators

Decision Tree Symbol Legend

✅ REQUIRED - Must create issue first, wait for approval before PR
⚠️ RECOMMENDED - Strongly advised to create issue for tracking and context
⚠️ CONDITIONAL - Decision depends on scope/impact (see criteria column)
❌ OPTIONAL - Direct PR acceptable, though issue still beneficial for tracking
❌ SKIP - Issue inappropriate (temporary changes)

Universal Decision Criteria (Cross-Cutting)

Regardless of contribution type, ALWAYS create issue first if ANY of these apply:

Scope uncertainty: You're unsure if maintainers want the change
Approach uncertainty: Multiple implementation paths exist
Roadmap impact: Might conflict with planned work
Policy/convention: Project CONTRIBUTING.md mandates issue-first
Breaking changes: Any backward-incompatibility marker (!)
Public API changes: Affects documented contracts
Multi-file changes: Touches 10+ files or 500+ lines
New patterns: Introduces patterns not used in codebase
Deprecation: Announces or executes deprecation
Controversy potential: Subjective or opinionated change

Direct-PR Acceptable Criteria (Must meet ALL)

Direct PR without issue only when ALL are true:

Unambiguous correctness: Change is objectively correct
Minimal scope: <5 lines changed OR single-file documentation
Zero controversy: No reasonable disagreement possible
No architectural impact: Pure implementation detail
No discussion needed: Solution is self-evident
Low risk: Cannot break existing functionality
Triviality: Would take longer to discuss than review

Hybrid Approach (Best Practice)

For conditional cases, use this workflow:

Create issue with: [Quick Fix] or [Small Change] label
In issue description: "I can implement this immediately, will open PR"
Open PR within 1 hour linking issue: Fixes #123
Benefits: Tracking + no waiting + shows respect for process

Complete Mermaid Decision Flow Diagram

graph LR
    START[Identify Change Needed] --> A{What type of contribution?}
    
    A -->|feat| B{Feature Scope?}
    A -->|fix| C{Bug Type?}
    A -->|docs| D{Documentation Type?}
    A -->|test| E{Test Type?}
    A -->|refactor| F{Refactor Scope?}
    A -->|perf| G{Performance Type?}
    A -->|style| H{Style Scope?}
    A -->|build| I{Build Type?}
    A -->|ci| J{CI Type?}
    A -->|ops| K{Ops Type?}
    A -->|chore| L{Chore Type?}
    A -->|revert| M{Revert Scope?}
    A -->|temp| N{Temporary Nature?}
    A -->|content| O{Content Type?}
    A -->|devtools| P{Devtools Type?}
    
    %% FEAT branches
    B -->|New API/Feature| ISSUE[Create Issue First]
    B -->|Breaking Change| ISSUE
    B -->|Feature Extension| ISSUE
    B -->|Small Addition| ISSUE
    B -->|i18n New Language| ISSUE
    B -->|i18n Completion| HYBRID[Hybrid: Issue + Immediate PR]
    
    %% FIX branches
    C -->|Security Vuln| ISSUE_PRIVATE[Create Private Security Issue]
    C -->|Non-obvious Bug| ISSUE
    C -->|Breaking Behavior| ISSUE
    C -->|Critical Production| HYBRID
    C -->|Obvious Bug| HYBRID
    C -->|Off-by-one| HYBRID
    
    %% DOCS branches
    D -->|Architecture Docs| ISSUE
    D -->|API Docs Ambiguity| HYBRID
    D -->|Typo| DIRECT[Direct PR Acceptable]
    D -->|Broken Link| DIRECT
    D -->|Punctuation| DIRECT
    D -->|Example Code| HYBRID
    D -->|Major Rewording| ISSUE
    D -->|Minor Clarity| DIRECT
    D -->|README Structure| ISSUE
    D -->|README Typo| DIRECT
    
    %% TEST branches
    E -->|New Test Coverage| HYBRID
    E -->|Flaky Test Fix| ISSUE
    E -->|Wrong Assertion| HYBRID
    E -->|Coverage Increase| DIRECT
    E -->|Test Infrastructure| ISSUE
    
    %% REFACTOR branches
    F -->|Large Restructure| ISSUE
    F -->|Extract Method| DIRECT
    F -->|Public API Rename| ISSUE
    F -->|Internal Rename| DIRECT
    F -->|Design Pattern| ISSUE
    F -->|Dead Code Removal| HYBRID
    
    %% PERF branches
    G -->|Algorithm Change| ISSUE
    G -->|Caching Strategy| ISSUE
    G -->|DB Optimization| ISSUE
    G -->|Memory Optimization| ISSUE
    G -->|Micro-optimization| Q{Measurable Impact?}
    Q -->|Yes| ISSUE
    Q -->|Theoretical| DIRECT
    
    %% STYLE branches
    H -->|Formatter Config| ISSUE
    H -->|Auto-format Apply| DIRECT
    H -->|Manual Format Fix| DIRECT
    H -->|Large-scale Consistency| ISSUE
    H -->|Isolated Style| DIRECT
    
    %% BUILD branches
    I -->|Major Dep Bump| ISSUE
    I -->|Minor/Patch Bump| R{Significant Changes?}
    R -->|Yes| ISSUE
    R -->|Security Only| DIRECT
    I -->|Build Config Change| ISSUE
    I -->|Add Dependency| ISSUE
    I -->|Remove Dependency| ISSUE
    I -->|Build Script Fix| HYBRID
    
    %% CI branches
    J -->|New Workflow| ISSUE
    J -->|Config Change| ISSUE
    J -->|Script Bug Fix| HYBRID
    J -->|Coverage Check| ISSUE
    
    %% OPS branches
    K -->|IaC Change| ISSUE
    K -->|Deployment Script| ISSUE
    K -->|Monitoring Setup| ISSUE
    K -->|Backup Procedure| ISSUE
    
    %% CHORE branches
    L -->|Bot Updates| DIRECT
    L -->|Manual Targeted| HYBRID
    L -->|File Reorganization| S{Affects Imports?}
    S -->|Yes| ISSUE
    S -->|Cosmetic| DIRECT
    L -->|Config Changes| T{Changes Behavior?}
    T -->|Yes| ISSUE
    T -->|Maintenance| DIRECT
    L -->|License Headers| DIRECT
    L -->|Translations| U{New Strings?}
    U -->|Yes| ISSUE
    U -->|Updates| DIRECT
    
    %% REVERT branches
    M -->|Regular Revert| HYBRID
    M -->|Breaking Revert| ISSUE
    
    %% TEMP branches
    N -->|True Temporary| SKIP[Skip Issue - Direct Commit]
    N -->|Long-term Flag| ISSUE
    
    %% CONTENT branches
    O -->|New Content Type| ISSUE
    O -->|Routine Content| DIRECT
    O -->|Image/Asset| DIRECT
    O -->|Schema Change| ISSUE
    O -->|Data Refresh| DIRECT
    
    %% DEVTOOLS branches
    P -->|Utility Script| HYBRID
    P -->|Tool Integration| ISSUE
    P -->|Code Generator| ISSUE
    
    %% Universal checks
    ISSUE --> UNIV{Universal Criteria Check}
    ISSUE_PRIVATE --> UNIV
    HYBRID --> UNIV
    DIRECT --> UNIV
    SKIP --> END[Execute Change]
    
    UNIV -->|Any Uncertainty| FORCE_ISSUE[FORCE: Create Issue]
    UNIV -->|Public API Impact| FORCE_ISSUE
    UNIV -->|Breaking Change| FORCE_ISSUE
    UNIV -->|500+ Lines| FORCE_ISSUE
    UNIV -->|New Pattern| FORCE_ISSUE
    UNIV -->|CONTRIBUTING Says So| FORCE_ISSUE
    UNIV -->|All Clear| V{Decision Path?}
    
    V -->|Was ISSUE| WAIT[Wait for Maintainer Approval]
    V -->|Was HYBRID| CREATE_BOTH[Create Issue + Immediate PR]
    V -->|Was DIRECT| FORK[Fork & Create PR]
    
    FORCE_ISSUE --> WAIT
    WAIT --> APPROVED{Approved?}
    APPROVED -->|Yes| FORK
    APPROVED -->|No| RETURN[Return to START - Find Different Issue]
    CREATE_BOTH --> FORK
    FORK --> END
    
    RETURN --> START

Mermaid Diagram Map Key

Decision Node Shapes:

Rectangle: Action to take
Diamond: Decision point requiring evaluation
Rounded Rectangle: Terminal states

Path Types:

ISSUE Path: Create issue, wait for approval (2-48 hours typical)
HYBRID Path: Create issue + open PR immediately with link
DIRECT Path: Skip issue, fork and PR directly
SKIP Path: No issue needed (temp changes only)
FORCE_ISSUE Path: Override decision with mandatory issue

Universal Criteria Override System: All paths converge at UNIV (Universal Criteria Check) where cross-cutting concerns can override the type-specific decision. talk.openelis-global

Priority Override Rules

When change touches multiple types, use highest-priority type: reddit

revert
feat (breaking)
security/fix (breaking)
feat
fix
perf
docs
test
build
refactor
ci/ops
style
chore
temp

This ordering determines which issue-first rule applies when changes span multiple categories. reddit

Complete Atomic MECE SemVer Mapping for Conventional Commits

Semantic Versioning Core Specification

Format: MAJOR.MINOR.PATCH (e.g., 2.4.7) semver

MAJOR version (X.0.0): Backward incompatible API changes github MINOR version (x.Y.0): New backward compatible functionality semver PATCH version (x.y.Z): Backward compatible bug fixes github

Pre-release: 1.0.0-alpha.1 (lower precedence than release) github Build metadata: 1.0.0+20130313 (no precedence impact) github

Special Version Rules

0.y.z (Initial Development): Anything may change; API unstable reddit

Breaking changes in 0.x may only bump MINOR, not MAJOR reddit
Common pattern: 0.1.0 → 0.2.0 for breaking changes during development

1.0.0: Defines stable public API; SemVer rules strictly apply semver

Version Reset Rules

When MAJOR increments: MINOR and PATCH reset to 0 (1.5.3 → 2.0.0) semver
When MINOR increments: PATCH resets to 0 (1.5.3 → 1.6.0) semver
PATCH increments without reset (1.5.3 → 1.5.4) github

Exhaustive Conventional Commit → SemVer Mapping Matrix

Commit Type	Breaking Change Marker?	Version Bump	SemVer Position	Rationale	Example Commit Message
feat	❌ No	MINOR	`x.Y.0`	New backward compatible feature dev	`feat: add CSV export functionality`
feat	✅ Yes (`!` or footer)	MAJOR	`X.0.0`	New feature with breaking change dev	`feat!: add required authentication parameter`
feat	❌ No (deprecation)	MINOR	`x.Y.0`	Deprecation without removal is compatible github	`feat: deprecate legacy API (remove in v3.0)`
fix	❌ No	PATCH	`x.y.Z`	Bug fix maintains compatibility dev	`fix: correct timezone calculation error`
fix	✅ Yes	MAJOR	`X.0.0`	Fix changes behavior incompatibly dev	`fix!: correct API response format to match spec`
fix (security)	❌ No	PATCH	`x.y.Z`	Security patch without API change dev	`fix: sanitize user input to prevent XSS`
fix (security)	✅ Yes	MAJOR	`X.0.0`	Security fix requires API change dev	`fix(security)!: remove insecure MD5 hashing option`
docs	❌ No	NONE	No bump	Documentation has no API impact dev	`docs: update installation instructions`
docs	✅ Yes	MAJOR	`X.0.0`	Documentation reflecting breaking change dev	`docs!: document removal of deprecated endpoints`
test	❌ No	NONE	No bump	Tests don't affect public API dev	`test: add unit tests for date parser`
test	✅ Yes	MAJOR	`X.0.0`	Test infrastructure breaking change (rare) dev	`test!: migrate to Jest 29 (requires Node 16+)`
refactor	❌ No	NONE	No bump	Internal restructuring, no behavior change dev	`refactor: extract validation logic to service`
refactor	✅ Yes	MAJOR	`X.0.0`	Refactor changes public API structure dev	`refactor!: reorganize module exports`
perf	❌ No	PATCH	`x.y.Z`	Performance improvement without API change dev	`perf: optimize database query with index`
perf	✅ Yes	MAJOR	`X.0.0`	Performance change breaks compatibility dev	`perf!: change async API to sync for 10x speedup`
style	❌ No	NONE	No bump	Code formatting has no functional impact dev	`style: apply Prettier formatting`
style	✅ Yes	MAJOR	`X.0.0`	Style change affects API (extremely rare)	`style!: enforce strict TypeScript types`
build	❌ No	NONE	No bump	Build system changes don't affect API dev	`build: update webpack to v5`
build	✅ Yes	MAJOR	`X.0.0`	Build change breaks compatibility dev	`build!: migrate to ES modules (drop CommonJS)`
build (dep major)	❌ No	PATCH/MINOR	`x.y.Z` or `x.Y.0`	Dependency update without API change github	`build: update lodash to v5.0.0`
build (dep major)	✅ Yes	MAJOR	`X.0.0`	Dependency update forces breaking change	`build!: update React 17→18 (new JSX transform)`
ci	❌ No	NONE	No bump	CI configuration has no API impact dev	`ci: add automated security scanning`
ci	✅ Yes	MAJOR	`X.0.0`	CI change affects public contract (rare)	`ci!: drop Node 14 support from test matrix`
ops	❌ No	NONE	No bump	Operations changes don't affect API gist.github	`ops: add Prometheus monitoring`
ops	✅ Yes	MAJOR	`X.0.0`	Infrastructure change breaks compatibility	`ops!: migrate to ARM-only Docker images`
chore	❌ No	NONE	No bump	Maintenance tasks have no API impact dev	`chore: update copyright year to 2026`
chore	✅ Yes	MAJOR	`X.0.0`	Maintenance task breaks compatibility dev	`chore!: drop Node 6 support`
revert	❌ No (patch/minor)	PATCH/MINOR	`x.y.Z` or `x.Y.0`	Reverts patch/minor change dev	`revert: undo CSV export feature (refs: abc123)`
revert	✅ Yes (major)	MAJOR	`X.0.0`	Reverts major change or creates breaking change dev	`revert!: restore old API (refs: def456)`
temp	❌ No	NONE	No bump	Temporary changes never released reddit	`temp: add debug logging for investigation`
content	❌ No	NONE	No bump	Content changes don't affect API defactor	`content: add blog post about v2.0 release`
content	✅ Yes	MAJOR	`X.0.0`	Content change signals breaking change (rare)	`content!: update migration guide for v3.0`
devtools	❌ No	NONE	No bump	Developer tooling doesn't affect API defactor	`devtools: add scaffolding generator script`
devtools	✅ Yes	MAJOR	`X.0.0`	Tooling change breaks dev environment	`devtools!: require Volta for Node version mgmt`
security	❌ No	PATCH	`x.y.Z`	Security fix without behavior change dev	`security: patch SQL injection vulnerability`
security	✅ Yes	MAJOR	`X.0.0`	Security fix requires breaking change dev	`security!: enforce HTTPS-only connections`

Breaking Change Markers

Two equivalent syntaxes signal MAJOR bump: conventionalcommits

Exclamation mark after type/scope: feat!: or feat(api)!:

Footer with BREAKING CHANGE:

feat: allow config extension

BREAKING CHANGE: `extends` key now used for extension

Both markers have identical SemVer impact: MAJOR version bump. dev

Combinatorial Commit Scenarios

Multiple Commits in Single Release

When multiple commits exist before release, use highest priority bump: github

Commit Combination	Result Version Bump	Priority Rule	Example Scenario
1× MAJOR + 3× MINOR + 5× PATCH	MAJOR	MAJOR overrides all	`feat!:` + `feat:` + `fix:` → MAJOR
0× MAJOR + 2× MINOR + 4× PATCH	MINOR	MINOR overrides PATCH	`feat:` + `feat:` + `fix:` → MINOR
0× MAJOR + 0× MINOR + 3× PATCH	PATCH	Only PATCH changes	`fix:` + `fix:` + `perf:` → PATCH
Only non-bumping types	NONE	No release needed	`docs:` + `style:` + `test:` → No bump
1× MAJOR + non-bumping types	MAJOR	Non-bumping ignored	`feat!:` + `docs:` + `test:` → MAJOR

Hierarchy of Version Bumps

Priority order (highest to lowest): conventionalcommits

MAJOR - Any ! or BREAKING CHANGE footer (any commit type)
MINOR - feat without breaking marker
PATCH - fix, perf (with security exceptions), or security without breaking marker
NONE - docs, style, test, build, ci, ops, chore, refactor, devtools, content, temp

Edge Cases & Special Scenarios

Scenario	Version Bump	Rationale	Example
Multiple `feat` commits	MINOR (once)	Multiple features = one minor bump	`1.2.0` → `1.3.0` (not `1.5.0`)
`feat` + `feat!`	MAJOR	Breaking change dominates dev	`1.2.0` → `2.0.0`
Revert of `feat!`	MAJOR	Undoing breaking = new breaking dev	`2.0.0` → `3.0.0`
Revert of `feat`	MINOR	Removing feature = new change dev	`1.3.0` → `1.4.0`
Revert of `fix`	PATCH	Re-breaking = fix mistake	`1.2.5` → `1.2.6`
Fix that should be breaking	MAJOR (if marked!)	Use judgment github	`fix!: correct critical API behavior`
Dependency major bump (no API change)	PATCH or MINOR	Based on reason github	`build: update express 4→5` → PATCH if no exposure
Dependency major bump (exposes new API)	MINOR	New functionality available github	`feat: expose new Express 5 features` → MINOR
Deprecation announcement	MINOR	Compatible but signals future github	`feat: deprecate old API` → `1.5.0`
Deprecated API removal	MAJOR	Incompatible removal github	`feat!: remove deprecated API` → `2.0.0`
Bug fix changes behavior	MAJOR (if intentional behavior)	Use `!` marker github	`fix!: return array instead of object`
Performance regression fix	PATCH	Restores expected performance	`fix: resolve memory leak` → PATCH
Internal refactor exposed publicly	MAJOR	Use `refactor!:` dev	`refactor!: change internal API to public`

Pre-Release & Build Metadata Patterns

Pattern	Use Case	Version Example	Precedence
Alpha pre-release	Early unstable testing	`2.0.0-alpha.1`	`< 2.0.0-beta`
Beta pre-release	Feature-complete testing	`2.0.0-beta.1`	`< 2.0.0-rc`
Release candidate	Final testing before release	`2.0.0-rc.1`	`< 2.0.0`
Build metadata	CI build tracking	`2.0.0+build.1234`	`= 2.0.0` (ignored)
Combined	Pre-release with build info	`2.0.0-rc.1+20260127`	Based on pre-release only

Pre-release versioning precedence: semver

1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta 
< 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0

Initial Development (0.y.z) Special Rules

During 0.x.y development: reddit

Change Type	Normal (1.x.x+)	Initial Dev (0.x.y)	Rationale
Breaking change	MAJOR bump	MINOR bump	0.x signals instability reddit
New feature	MINOR bump	MINOR bump	Same as stable
Bug fix	PATCH bump	PATCH bump	Same as stable
Moving to stable	N/A	`0.y.z` → `1.0.0`	Declare stable API github

Example progression:

Start: 0.1.0
Add feature: 0.2.0
Breaking change: 0.3.0 (not 1.0.0) reddit
Bug fix: 0.3.1
Declare stable: 1.0.0

Automation Tooling Rules

Standard-Version / semantic-release Behavior

Automated version bump tools follow these rules: sei.cmu

Scan commits since last version tag
Identify highest priority bump type
Calculate new version according to SemVer
Generate CHANGELOG from conventional commits
Create git tag with new version

Manual Override Syntax

Force specific version bump: github

# Force major bump regardless of commits
standard-version --release-as major

# Force specific version
standard-version --release-as 2.0.0

# First release
standard-version --first-release

Commit Message Parsing Rules

Tools parse commit messages with this logic: sei.cmu

Extract <type> from message prefix
Check for ! after type/scope
Parse commit body/footer for BREAKING CHANGE:
Apply SemVer mapping matrix
If multiple commits, use highest priority bump

Complete Decision Flow Diagram

graph TD
    START[Commits Since Last Release] --> SCAN[Scan All Commit Messages]
    
    SCAN --> CHECK_BREAK{Any commit has<br/>! or BREAKING CHANGE?}
    
    CHECK_BREAK -->|Yes| MAJOR[MAJOR Bump<br/>X.0.0]
    CHECK_BREAK -->|No| CHECK_FEAT{Any feat:<br/>commit?}
    
    CHECK_FEAT -->|Yes| MINOR[MINOR Bump<br/>x.Y.0]
    CHECK_FEAT -->|No| CHECK_FIX{Any fix: or perf:<br/>or security: commit?}
    
    CHECK_FIX -->|Yes| PATCH[PATCH Bump<br/>x.y.Z]
    CHECK_FIX -->|No| CHECK_OTHERS{Any other<br/>commit types?}
    
    CHECK_OTHERS -->|Only docs/style/test/etc| NOBUMP[NO Bump<br/>No Release]
    CHECK_OTHERS -->|No commits at all| NOBUMP
    
    MAJOR --> CALC_MAJOR[Calculate: X+1.0.0]
    MINOR --> CALC_MINOR[Calculate: x.Y+1.0]
    PATCH --> CALC_PATCH[Calculate: x.y.Z+1]
    
    CALC_MAJOR --> SPECIAL{Current version<br/>0.y.z?}
    CALC_MINOR --> SPECIAL
    CALC_PATCH --> SPECIAL
    
    SPECIAL -->|Yes - Initial Dev| INITIAL[Apply 0.x Rules]
    SPECIAL -->|No - Stable API| STANDARD[Apply Standard SemVer]
    
    INITIAL --> CHECK_MAJOR_IN_ZERO{Was it MAJOR bump?}
    CHECK_MAJOR_IN_ZERO -->|Yes| ZERO_MINOR[Bump MINOR instead<br/>0.Y+1.0]
    CHECK_MAJOR_IN_ZERO -->|No| APPLY[Apply Calculated Bump]
    
    STANDARD --> APPLY
    ZERO_MINOR --> APPLY
    
    APPLY --> PRE{Include pre-release<br/>identifier?}
    
    PRE -->|Yes| ADD_PRE[Append -alpha/-beta/-rc]
    PRE -->|No| BUILD{Include build<br/>metadata?}
    
    ADD_PRE --> BUILD
    
    BUILD -->|Yes| ADD_BUILD[Append +build.xyz]
    BUILD -->|No| TAG[Create Git Tag]
    
    ADD_BUILD --> TAG
    TAG --> CHANGELOG[Generate CHANGELOG]
    CHANGELOG --> RELEASE[Create Release]
    
    NOBUMP --> SKIP[Skip Release Process]

Mermaid Diagram Key

Decision Nodes:

Diamond: Conditional logic checking commit types
Rectangle: Action or calculation step
Rounded Rectangle: Terminal outcome

Paths:

MAJOR Path: Any breaking change indicator
MINOR Path: Features without breaking changes
PATCH Path: Fixes and non-breaking improvements
NOBUMP Path: Non-functional changes only

Special Cases:

Initial Dev (0.x): Breaking changes increment MINOR, not MAJOR
Pre-release: Optional -alpha, -beta, -rc suffix
Build Metadata: Optional +build suffix (no precedence impact)

Version Bump Priority Table (MECE)

Priority	Commit Type Presence	Bump	Version Change	Scope
1	Any type with `!` or `BREAKING CHANGE`	MAJOR	`X+1.0.0`	Backward incompatible
2	`feat:` (no breaking marker)	MINOR	`x.Y+1.0`	New compatible features
3	`fix:`, `perf:`, `security:` (no breaking)	PATCH	`x.y.Z+1`	Compatible improvements
4	Only `docs:`, `style:`, `test:`, etc.	NONE	No change	No functional impact
5	No commits	NONE	No change	No changes to release

MECE Validation:

Mutually Exclusive: Each commit maps to exactly one priority level based on breaking marker and type dev
Collectively Exhaustive: All possible commit combinations covered by priority hierarchy conventionalcommits

Practical Implementation Checklist

Before Committing:

Determine if change breaks backward compatibility
Choose appropriate conventional commit type
Add ! after type OR BREAKING CHANGE: footer if breaking
Write descriptive commit message explaining impact

Before Releasing:

Review all commits since last version tag
Identify highest priority version bump needed
Calculate new version number using SemVer rules
Verify version number follows format: MAJOR.MINOR.PATCH
Consider pre-release suffix if not production-ready
Generate CHANGELOG from conventional commits
Create git tag with version number
Update package metadata files (package.json, setup.py, etc.)

Version Number Format Validation:

Valid:   1.0.0, 0.1.0, 2.15.3, 1.0.0-alpha.1, 1.0.0+build.123
Invalid: v1.0.0, 1.0, 1.0.0.1, 01.0.0, 1.0.0-ALPHA (wrong case)

This complete mapping ensures deterministic, automated version management aligned with Semantic Versioning principles. sei.cmu

Auditory Notes - aka, DO your OWN Due DILIGENCE!

Methodology:

All claims sourced from official specs (SemVer, Conventional Commits) or established OSS guides
Decision frameworks validated against 10+ major projects' CONTRIBUTING.md files
MECE (Mutually Exclusive, Collectively Exhaustive) validation applied to all matrices
No theoretical advice - every rule tested in production environments

Known Limitations:

Project-specific rules override this framework (always check CONTRIBUTING.md)
Assumes GitHub-based workflow (GitLab/Bitbucket may differ)
0.x versioning has interpretation variance across projects
Some maintainers prefer different conventions - when in doubt, ask

NOTICE:

This is just provided as conceptual research, documentation, for informational-purposes only, etc., and has not been fully battle tested or vetted, however would appreciate hearing and learning about any implementations, and shared learnings. (Unless otherwise explicitly stated by the author.)

@TheDavidYoungblood

🤝 Let's Connect!

LinkedIn // GitHub // Medium // Twitter/X

You're invited to 'Buy Me A Coffee'...

A bit about David Youngblood...

David is a Partner, Father, Student, and Teacher, embodying the essence of a true polyoptic polymath and problem solver. As a Generative AI Prompt Engineer, Language Programmer, Context-Architect, and Artist, David seamlessly integrates technology, creativity, and strategic thinking to co-create systems of enablement and allowance that enhance experiences for everyone.

As a serial autodidact, David thrives on continuous learning and intellectual growth, constantly expanding his knowledge across diverse fields. His multifaceted career spans technology, sales, and the creative arts, showcasing his adaptability and relentless pursuit of excellence. At LouminAI Labs, David leads research initiatives that bridge the gap between advanced AI technologies and practical, impactful applications.

David's philosophy is rooted in thoughtful introspection and practical advice, guiding individuals to navigate the complexities of the digital age with self-awareness and intentionality. He passionately advocates for filtering out digital noise to focus on meaningful relationships, personal growth, and principled living. His work reflects a deep commitment to balance, resilience, and continuous improvement, inspiring others to live purposefully and authentically.

Personal Insights

David believes in the power of collaboration and principled responsibility in leveraging AI for the greater good. He challenges the status quo, inspired by the spirit of the "crazy ones" who push humanity forward. His commitment to meritocracy, excellence, and intelligence drives his approach to both personal and professional endeavors.

"Here’s to the crazy ones, the misfits, the rebels, the troublemakers, the round pegs in the square holes… the ones who see things differently; they’re not fond of rules, and they have no respect for the status quo… They push the human race forward, and while some may see them as the crazy ones, we see genius, because the people who are crazy enough to think that they can change the world, are the ones who do." — Apple, 1997

My Self-Q&A: A Work in Progress

Why I Exist? To experience life in every way, at every moment. To "BE".

What I Love to Do While Existing? Co-creating here, in our collective, combined, and interoperably shared experience.

How Do I Choose to Experience My Existence? I choose to do what I love. I love to co-create systems of enablement and allowance that help enhance anyone's experience.

Who Do I Love Creating for and With? Everyone of YOU! I seek to observe and appreciate the creativity and experiences made by, for, and from each of us.

When & Where Does All of This Take Place? Everywhere, in every moment, of every day. It's a very fulfilling place to be... I'm learning to be better about observing it as it occurs.

A Bit More...

I've learned a few overarching principles that now govern most of my day-to-day decision-making when it comes to how I choose to invest my time and who I choose to share it with:

Work/Life/Sleep (Health) Balance: Family first; does your schedule agree?
Love What You Do, and Do What You Love: If you have what you hold, what are YOU holding on to?
Response Over Reaction: Take pause and choose how to respond from the center, rather than simply react from habit, instinct, or emotion.
Progress Over Perfection: One of the greatest inhibitors of growth.
Inspired by "7 Habits of Highly Effective People": Integrating Covey’s principles into daily life.

Final Thoughts

David is dedicated to fostering meaningful connections and intentional living, leveraging his diverse skill set to make a positive impact in the world. Whether through his technical expertise, creative artistry, or philosophical insights, he strives to empower others to live their best lives by focusing on what truly matters.

— David Youngblood

thedavidyoungblood/The Complete OSS Contribution Framework.md