Proposal + Discussion On New Tiers/Tags for Libraries Under the BDK Org

[thunderbiscuit]

We've been discussing the idea of using categories for the libraries under the Bitcoindevkit GitHub Org. This issue aims to help us hash out the best way to do this given our objectives. Once a good plan of action is decided, we can then:

• Add a page to the website here and maybe the Book of BDK with our official policy for the categories.
• Assign a category to all our libraries, as well as the other required elements as decided here (number of official maintainers, etc.).

Objectives

Here are what I think our current objectives with this initiative:

1. Help define for ourselves the types of libraries that are currently under the org, and the priorities given the resources we have and the users we have.
2. Communicate to users of the libraries the things they can expect from them and from us, and the general approach and workflow the different libraries might have. Not all libraries are maintained the same way (requirements for review, test coverage, extensiveness of documentation, etc.) and defining the types of buckets will help.
3. Help us define how and when libraries might qualify for entering the org. Over the years we have had a number of requests for adding libraries to the organization; having a clear definition of the types of libraries we accept under the org will help us cut the line on where/when a library might be a good candidate for us.

If you think of other objectives comment below and I'll add them to this list. Further posts will propose ideas on how to implement these objectives.

[thunderbiscuit]

After discussing it with other devs, 2 main approaches emerge in my mind. I'll try to make the best case for both of them here, and we can use them as a stepping stone for further ideas by picking the best one or simply merging the best part of each.

1. A sort of flat hierarchy where the categories/tags don't have a natural ordering, but rather simply express how we think of the libraries and what can users expect from each. Libraries can move between tags of course as required over time. Examples:
   • core/community/nursery/retired
   • production/supported/experimental/retired
2. A more layered approach, where the categories/tiers express how we maintain the libraries and their level of production-readiness. Again the libraries can move between categories as needed over time. Examples:
   • tier1/tier2/nursery
   • full support/mainained/best effort/experimental

[thunderbiscuit]

Proposal Example 1

Our organization maintains repositories across different maturity and maintenance levels. To help you navigate our projects, we've categorized them into four distinct groups.

Core

Our production-critical libraries that form the foundation of the BDK ecosystem. These repositories receive the highest level of attention and maintenance.

What to expect:

• 2 official maintainers, supported by the BDK Foundation
• Comprehensive test coverage and CI/CD
• Regular security updates and dependency maintenance
• Active monitoring and quick response to issues
• Semantic versioning with clear release notes
• Extensive documentation and examples

Supported or Community

Well-maintained libraries that are production-ready but serve more specific use cases or see less frequent updates. Those li

What to expect:

• 2 official maintainers
• The maintainers might be BDK Foundation developers, users of the library from a different project, or devs in the industry
• Good test coverage and automated builds
• Regular maintenance and bug fixes
• Response to issues within a reasonable timeframe
• Documentation and usage examples

Nursery

Early-stage projects. These may be unstable or undergoing rapid iteration. These projects aim to over time become either core or supported project, but are not yet ready.

What to expect:

• Incomplete or evolving APIs
• Limited or no backward compatibility guarantees
• Potentially community-driven maintenance
• Minimal documentation
• Potential for major changes or deprecation

Docs

Documentation repositories including tutorials, guides, architecture decision records, and learning resources.

What to expect:

• Educational content and examples
• Getting started guides
• API references and specifications
• Best practices and patterns
• Sample applications

[thunderbiscuit]

Proposal Example 2

Our organization maintains repositories with different support commitments. This classification helps you understand what level of maintenance and support you can expect from each project.

Tier 1: Fully Supported

Mission-critical libraries that receive our highest level of support and maintenance commitment.

Support Level:

• Security Updates: Patching of critical vulnerabilities
• Maintenance: Active development and regular releases
• Documentation: Comprehensive guides, API docs, and examples
• Compatibility: Long-term stability guarantees and clear migration paths
• Testing: Extensive test coverage (>80%) and continuous integration

Best for: Production systems, enterprise deployments, and core infrastructure.

Tier 2: Maintained

Solid, production-ready libraries with regular maintenance but without strict SLAs.

Support Level:

• Response Time: Issues triaged within 1-2 weeks
• Security Updates: Security patches released promptly
• Maintenance: Regular bug fixes and dependency updates
• Documentation: Good documentation with usage examples
• Compatibility: Semantic versioning with deprecation notices
• Testing: Good test coverage and automated builds

Best for: Feature-specific implementations, integrations, and secondary dependencies.

Community: Best Effort

Community-driven, experimental, or third-party maintained projects with no formal support commitment.

Support Level:

• Response Time: No guaranteed response time
• Security Updates: Community-driven security responses
• Maintenance: Sporadic updates based on community contributions
• Documentation: May be minimal or work-in-progress
• Compatibility: No guarantees; breaking changes may occur
• Testing: Variable test coverage

Best for: Experimentation, prototyping, specialized use cases, or when you're willing to contribute.

Documentation & Resources

Educational materials, architectural documentation, and learning resources.

What's Included:

• Getting started guides and tutorials
• API reference documentation
• Architecture decision records (ADRs)
• Best practices and design patterns
• Example applications and code samples
• Migration guides

Support Policy

What Tier 1 & Tier 2 Include

• Bug fixes for reported issues
• Security vulnerability patches
• Dependency updates for compatibility
• Response to GitHub issues and pull requests

Version Support

• Tier 1: We support the current major version and one prior major version
• Tier 2: We support the current major version
• Community: No version support guarantees

[notmandatory]

I agree with the objectives and based on that lean to proposal 1 with support policies from 2. I also want to incorporate our foundations mission statement. I don't see "Docs and Resources" as a different category, but instead I see them as required artifacts for fully maintained projects. I also prefer "Community" for the 2nd group. I'd like to find a better term than Core since it's so overloaded from bitcoin core and our bdk_core lib but I can't think of anything else right now.

BDK Foundation By-Laws mission statement:
The primary purpose of the Foundation (collectively, the "Purpose") is to:
(a) advance the Bitcoin software development industry by fostering innovation, promoting best practices, and improving the overall ecosystem;
(b) support the promotion, research, development, maintenance, and security of the Bitcoin Dev Kit (BDK) libraries and other projects supporting the Bitcoin software industry (the "Projects");
(c) support and empower Bitcoin software developers through educational initiatives, open-source project support, and industry-wide collaboration;
(d) manage the technical infrastructure underlying the development of the Projects;
(e) manage and steward the BDK trademark and other assets of the Foundation;
(f) undertake such other activities as may from time to time be appropriate to further the purposes and achieve the goals set forth above.
In furtherance of these efforts, the Foundation shall seek to solicit the participation of all interested parties on a fair, equitable, and open basis.

Something like this:

Proposal Example 3

The purposed of this organization is to advance the Bitcoin software development industry by fostering innovation, promoting best practices, and improving the overall ecosystem. To this end we provide the technical infrastructure to maintain a number of software projects across different maturity levels. To help you navigate these projects we've categorized them into three distinct groups.

Core

The libraries that form the core of the BDK ecosystem. These repositories receive the highest level of attention and maintenance.

What to expect:

• Two official maintainers
• Maintainers are supported by grant funding from the BDK Foundation
• A robust community of users and volunteer maintainers
• Comprehensive test coverage and CI/CD
• Security updates and dependency maintenance
• Security updates back ported to prior major release
• Active monitoring and fast response to issues
• Semantic versioning with clear release notes
• Data schema stability guarantees and clear migration paths
• Extensive documentation (API, tutorials, guides, etc.) with code examples
• Example applications

Community

Well-maintained libraries that serve more specific use cases and see less frequent updates. These repositories rely more on community contributions for maintenance.

What to expect:

• Two official maintainers
• Maintained by volunteers from the community
• Maintainers may receive grant funding from the BDK Foundation
• A robust community of users and volunteer maintainers
• Comprehensive test coverage and CI/CD
• Security updates and dependency maintenance
• Semantic versioning with clear release notes
• Response to issues within a reasonable timeframe
• Documentation (API) with code examples

Nursery

Early-stage projects. These may be unstable or undergoing rapid iteration. These projects aim to over time become either Core or Community projects, but are not yet ready.

What to expect:

• At least one official maintainer
• Maintained by volunteers from the community
• Incomplete or evolving APIs
• Only basic test coverage and CI/CD
• Limited or no backward compatibility guarantees
• Minimal documentation
• Potential for major changes or deprecation

Table

I'm also imaging how this would look in a table form:

	Core	Community	Nursery
Maintainers	2	2	1
BDKF Grant Funding	Yes	Optional	No
Community Support	Yes	Yes	No
Comprehensive Testing and CI/CD	Yes	Yes	No
Security and Dependency Updates	Yes	Yes	No
Semantic Versioning, Release Notes	Yes	Yes	No
API Documentation, Code Examples	Yes	Yes	No
Back-ported Security Updates	Yes	No	No
Fast Response to Issues	Yes	No	No
Data Schema Stability, Migration	Yes	No	No
Tutorials, Guides, Example Apps	Yes	No	No

[nymius]

nursery is a bit odd, experimental is more extensively used.
Proposal 2 format is closer to SLAs, which I think is not the right framework to conceptualize the project yet.
So I prefer proposal 3, or 1.
I would remove or rephrase terms that are not clearly accountable, as robust, clear, fast, comprehensive and others.
For alternatives to core, essentials is less overloaded, and I think a better fit as it conveys which are "the minimal components to build a bitcoin application with BDK"