Contributing to the Mastering Blockchain Scalability

Thank you for your interest in contributing to the Mastering Blockchain Scalability! This document provides guidelines and instructions for contributing.

How to Contribute

Content Contributions

1. Choose a Topic

   • Check the current chapters in SUMMARY.md
   • Look for chapters marked with 🚧 (work in progress)
   • Review existing issues for content requests

2. Writing Guidelines

   • Use clear, concise language
   • Include practical examples where possible
   • Cite sources and references
   • Use markdown formatting
   • Include diagrams when helpful (place in /assets directory)

3. Technical Requirements

   • Write content in Markdown format
   • Place images in the /assets directory
   • Use relative links for internal references
   • Follow the existing chapter structure

Submission Process

1. Fork the Repository

   • Create a fork of this repository
   • Create a new branch for your changes

2. Make Your Changes

   • Write your content
   • Test all links and formatting
   • Ensure images are properly referenced

3. Submit a Pull Request

   • Create a pull request from your branch
   • Provide a clear description of your changes
   • Reference any related issues

Review Process

1. Your contribution will be reviewed for:

   • Technical accuracy
   • Writing quality
   • Formatting consistency
   • Completeness

2. You may be asked to make revisions

3. Once approved, your changes will be merged

Style Guide

Markdown Formatting

• Use ATX-style headers (# for h1, ## for h2, etc.)
• Use code blocks with language specification
• Use tables for structured data
• Use blockquotes for important notes

Content Structure

• Start each chapter with an overview
• Include clear section headers
• End with a summary or key takeaways
• Add references where applicable

Questions or Need Help?

• Create an issue for questions
• Join discussions in existing issues
• Reach out to maintainers

Thank you for helping make blockchain scalability knowledge accessible to everyone!

Validate the Book

Before opening a pull request, run:

python3 scripts/check-book.py
./scripts/build-book.sh

The checker rejects missing SUMMARY.md entries or targets, broken local links, duplicate figure numbers, and unmatched footnotes. A successful checker does not replace technical review or visual inspection of changed figures and print pages.

Editorial Style

Follow STYLE.md for canonical scalability terminology, units, benchmark reporting, security claims, and citation practice. New text should identify its trust and finality assumptions rather than calling a design "trustless" or "secure" without qualification.