Skip to content

Commit

Permalink
Added FAQ and README updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@BigLep
BigLep committed Apr 5, 2023
1 parent 085ed9d commit 15bf447
Show file tree
Hide file tree
Showing 2 changed files with 238 additions and 26 deletions.
91 changes: 65 additions & 26 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,18 +15,27 @@ Boxo 🍌
<!-- TOC -->

- [About](#about)
- [Motivation](#motivation)
- [What kind of components does Boxo have?](#what-kind-of-components-does-boxo-have)
- [Does Boxo == IPFS?](#does-boxo--ipfs)
- [Is everything related to IPFS in the Go ecosystem in this repo?](#is-everything-related-to-ipfs-in-the-go-ecosystem-in-this-repo)
- [Getting started](#getting-started)
- [Migrating to Boxo](#migrating-to-boxo)
- [Should I add my IPFS component to Boxo?](#should-i-add-my-ipfs-component-to-boxo)
- [Help](#help)
- [Governance and Access](#governance-and-access)
- [Release Process](#release-process)
- [Related Items](#related-items)
- [License](#license)
- [Motivation](#motivation)
- [Scope](#scope)
- [What kind of components does Boxo have?](#what-kind-of-components-does-boxo-have)
- [Does Boxo == IPFS?](#does-boxo--ipfs)
- [Is everything related to IPFS in the Go ecosystem in this repo?](#is-everything-related-to-ipfs-in-the-go-ecosystem-in-this-repo)
- [Consuming](#consuming)
- [Getting started](#getting-started)
- [Migrating to Boxo](#migrating-to-boxo)
- [What is the deprecation and breaking change policy?](#what-is-the-deprecation-and-breaking-change-policy)
- [Development](#development)
- [Should I add my IPFS component to Boxo?](#should-i-add-my-ipfs-component-to-boxo)
- [Release Process](#release-process)
- [Why is the code coverage so bad?](#why-is-the-code-coverage-so-bad)
- [General](#general)
- [Help](#help)
- [What is the response time for issues or PRs filed?](#what-is-the-response-time-for-issues-or-prs-filed)
- [What are some projects that depend on this project?](#what-are-some-projects-that-depend-on-this-project)
- [Governance and Access](#governance-and-access)
- [Why is this named "Boxo"?](#why-is-this-named-boxo)
- [Additional FAQs](#additional-faqs)
- [License](#license)

<!-- /TOC -->

Expand All @@ -53,7 +62,10 @@ We’d also like to make life easier on ourselves as the maintainers by reducing

Boxo is not exhaustive nor comprehensive--there are plenty of useful IPFS protocols, specs, libraries, etc. that are not in Boxo. The goal of Boxo is to provide cohesive and well-maintained components for common IPFS use cases.

## What kind of components does Boxo have?
More details can also be found in the [Rationale FAQ](./docs/FAQ.md#rationale-faq).

## Scope
### What kind of components does Boxo have?

Boxo includes high-quality components useful for interacting with IPFS protocols, public and private IPFS networks, and content-addressed data, such as:

Expand All @@ -72,16 +84,14 @@ No. This repo houses some IPFS functionality written in Go that has been useful

No. Not everything related to IPFS is intended to be in Boxo. View it as a starter toolbox (potentially among multiple). If you’d like to build an IPFS implementation with Go, here are some tools you might want that are maintained by a group that has long term commitments to the IPFS project. There are certainly repos that others maintainer that aren't included here (e.g., ipfs/go-car) which are still useful to IPFS implementations. It's expected and fine for new IPFS functionality to be developed that won't be part of Boxo.

### Why is the code coverage so bad?

The code coverage of this repo is not currently representative of the actual test coverage of this code. Much of the code in this repo is currently covered by integration tests in [Kubo](https://github.com/ipfs/kubo). We are in the process of moving those tests here, and as that continues the code coverage will significantly increase.

## Getting started
## Consuming
### Getting started
See [examples](./examples/README.md).

If you are migrating to Boxo, see [Migrating to Boxo](#migrating-to-boxo).

## Migrating to Boxo
### Migrating to Boxo
Many Go modules under github.com/ipfs have moved here. Boxo provides a tool to ease this migration, which does most of the work for you:

* `cd` into the root directory of your module (where the `go.mod` file is)
Expand All @@ -97,7 +107,17 @@ We recommend upgrading to v0.8.0 first, and _then_ upgrading to the latest Boxo

If you encounter any challenges, please [open an issue](https://github.com/ipfs/boxo/issues/new/choose) and Boxo maintainers will help you.

## Should I add my IPFS component to Boxo?
### What is the deprecation and breaking change policy?
APIs may break between releases!

There are two types of breakages we're focused on and we'll handle them differently:
1. API refactor/change where it's still possible to accomplish the same functionality, but the API has changed. These changes may come within a release and in the worst case without prior formal notice. Usually thought there will be existing issues signaling the API breakage and notes about upcoming changes in the release notes.
2. Removal of a module or functionality. In this case, we'll do one release with deprecated go types and then remove it in the next release. Any types that have "deprecated" added will be called out in the release notes. Any types that are finally removed will also be called out in the release notes.

The above may cause alarm. We realize we're asking for trust that as maintainers we won't be half-hazard in decisions here. We see it as imperattive to strike a balance between giving predictability and stability for users, while also moving forward. We believe there is too much innovation and growth to be had to allow Boxo to be crushed by ossification. Our best medicine here is clear and advance communication, and then listening when there are concerns.

## Development
### Should I add my IPFS component to Boxo?
We happily accept external contributions! However, Boxo maintains a high quality bar, so code accepted into Boxo must meet some minimum maintenance criteria:

* Actively maintained
Expand All @@ -114,19 +134,38 @@ We happily accept external contributions! However, Boxo maintains a high quality

If you have some experimental component that you think would benefit the IPFS community, we suggest you build the component in your own repository until it's clear that there's community demand for it, and then open an issue/PR in this repository to discuss including it in Boxo.

## Help
### Release Process
To be documented: https://github.com/ipfs/boxo/issues/170

### Why is the code coverage so bad?

The code coverage of this repo is not currently representative of the actual test coverage of this code. Much of the code in this repo is currently covered by integration tests in [Kubo](https://github.com/ipfs/kubo). We are in the process of moving those tests here, and as that continues the code coverage will significantly increase.

## General
### Help

If you have questions, feel free to open an issue. You can also find the Boxo maintainers in [Filecoin Slack](https://filecoin.io/slack/) at #Boxo-maintainers. (If you would like to engage via IPFS Discord or ipfs.io Matrix, please drop into the #ipfs-implementers channel/room or file an issue, and we'll get bridging from #Boxo-maintainers to these other chat platforms.)

## Governance and Access
### What is the response time for issues or PRs filed?
TODO: fill this in. New issues and PRs to this repo are usually looked at on a weekly basis as part of [Kubo triage](https://pl-strflt.notion.site/Kubo-Issue-Triage-Notes-7d4983e8cf294e07b3cc51b0c60ede9a).

### What are some projects that depend on this project?
The exhaustive list is https://github.com/ipfs/boxo/network/dependents. Some notable projects include:
1. ipfs/kubo
2. filecoin-project/lotus
3. protocol/bifrost-gateway
4. ipfs-shipyard/ipfs-check

### Governance and Access
See [CODEOWNERS](./docs/CODEOWNERS) for the current maintainers list. Governance for graduating additional maintainers hasn't been established. Repo permissions are all managed through [ipfs/github-mgmt](https://github.com/ipfs/github-mgmt).

## Release Process
To be documented: https://github.com/ipfs/boxo/issues/170
### Why is this named "Boxo"?
See https://github.com/ipfs/boxo/issues/215.

## Related Items
* [Initial proposal for "Consolidate IPFS Repositories" that spawned this project](https://github.com/ipfs/kubo/issues/8543)
### Additional FAQs
See [docs/FAQ.md](./docs/FAQ.md).

## License
### License

[SPDX-License-Identifier: Apache-2.0 OR MIT](LICENSE.md)

Loading

0 comments on commit 15bf447

Please sign in to comment.