Skip to content

Conversation

@aabxtract
Copy link

Description

User story

As a new or returning Stacks developer, I want a clear, up-to-date overview of Stacks’ capabilities, upgrades, and ecosystem so that I can quickly understand what Stacks offers today and how to build on it with confidence.

This pull request modernizes the Stacks README to reflect the significant protocol, ecosystem, and developer experience changes that have occurred since the early Stacks releases.

  1. Motivation for change

The existing README was written several years ago and no longer accurately represents the current state of the Stacks blockchain. Since then, major developments such as sBTC, the Nakamoto upgrade, Clarity language advancements, and subnet-based scaling have been introduced.

Updating the README improves:

First-time developer onboarding

Accuracy of protocol representation

Discoverability of current documentation and tooling

  1. What was changed

Expanded the introduction to clearly describe Stacks as a Bitcoin-settled smart contract layer

Updated and clarified Stacks’ core features and design principles

Added sections covering:

sBTC and Bitcoin programmability

The Nakamoto upgrade and Bitcoin finality

Clarity language evolution

Subnets as a scaling solution

Refreshed links to current documentation, tooling, and ecosystem resources

Improved structure and readability for both new and experienced developers

  1. How does this impact application developers

Developers get a clearer understanding of:

How Bitcoin integrates with Stacks today

Which features are production-ready

Where to find accurate and current resources

Reduces confusion caused by outdated references

Improves onboarding speed and confidence for developers evaluating Stacks

No application logic or APIs are affected.

  1. Link to relevant issues and documentation

Stacks documentation: https://docs.stacks.co/

sBTC overview: https://stacks.co/sbtc

Stacks Improvement Proposals (SIPs): https://github.com/stacksgov/sips

Clarity documentation: https://book.clarity-lang.org/

No related issue number; this PR addresses documentation freshness and clarity.

  1. Examples of use cases and acceptance criteria

Use case:
A developer visiting the repository README should be able to:

Understand what Stacks is in under 5 minutes

Identify how Bitcoin is used (settlement, sBTC, PoX)

Locate the correct documentation to start building

Acceptance criteria

README accurately reflects current Stacks architecture

All referenced links are valid and point to maintained resources

No outdated protocol claims remain

Content is readable without prior Stacks knowledge

No code samples included, as this PR is documentation-only.

Expanded the introduction and features of Stacks, detailing its capabilities, innovations, and ecosystem. Updated links and resources for better clarity and accessibility.
@CLAassistant
Copy link

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants