From 773844896d022735eb1080aa1044f93751a5a4e4 Mon Sep 17 00:00:00 2001
From: github-actions <github-actions@github.com>
Date: Wed, 11 Dec 2024 13:53:31 +0000
Subject: [PATCH] doc: update contrib docs

---
 _contrib/CODE_OF_CONDUCT.md |  25 +++
 _contrib/CODE_STYLE.md      |  26 +++
 _contrib/COMMITS.md         |  69 ++++++
 _contrib/CONTRIBUTING.md    |  45 ++++
 _contrib/GOVERNANCE.md      | 115 ++++++++++
 _contrib/ISSUES.md          | 120 +++++++++++
 _contrib/MAINTAINERS.md     |  40 ++++
 _contrib/MSRV.md            |  13 ++
 _contrib/PULL_REQUESTS.md   |  53 +++++
 _contrib/ROADMAP-1.0.md     | 410 ++++++++++++++++++++++++++++++++++++
 _contrib/ROADMAP.md         | 115 ++++++++++
 _contrib/TENETS.md          | 102 +++++++++
 _contrib/VISION.md          | 234 ++++++++++++++++++++
 13 files changed, 1367 insertions(+)
 create mode 100644 _contrib/CODE_OF_CONDUCT.md
 create mode 100644 _contrib/CODE_STYLE.md
 create mode 100644 _contrib/COMMITS.md
 create mode 100644 _contrib/CONTRIBUTING.md
 create mode 100644 _contrib/GOVERNANCE.md
 create mode 100644 _contrib/ISSUES.md
 create mode 100644 _contrib/MAINTAINERS.md
 create mode 100644 _contrib/MSRV.md
 create mode 100644 _contrib/PULL_REQUESTS.md
 create mode 100644 _contrib/ROADMAP-1.0.md
 create mode 100644 _contrib/ROADMAP.md
 create mode 100644 _contrib/TENETS.md
 create mode 100644 _contrib/VISION.md

diff --git a/_contrib/CODE_OF_CONDUCT.md b/_contrib/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..4126d90
--- /dev/null
+++ b/_contrib/CODE_OF_CONDUCT.md
@@ -0,0 +1,25 @@
+---
+title: Code of Conduct
+layout: guide
+hyper_path: docs/CODE_OF_CONDUCT.md
+---
+
+## Be Kind
+
+- Don't be mean.
+- Insulting anyone is prohibited.
+- Harassment of any kind is prohibited.
+- If another person feels uncomfortable with your remarks, stop it.
+- If a moderator deems your comment or conduct as inappropriate, stop it.
+- Disagreeing is fine, but keep it to technical arguments. Never attack the person.
+- Give the benefit of the doubt. Assume good intentions.
+- Show empathy. There are 3 interpretations to any message: what we thought, what we said, and what they understand.
+- This does mean we exclude people who are not kind. We are happy to make that sacrifice.
+
+## Or Else
+
+- Violations of the Code of Conduct will result in 1 warning.
+- If the violation is major, a moderator may just ban immediately.
+- If a warning has already been given, a moderator will ban the offender.
+- There is no process for appealing a ban.
+- Any violations can be reported to sean@seanmonstar.com.
diff --git a/_contrib/CODE_STYLE.md b/_contrib/CODE_STYLE.md
new file mode 100644
index 0000000..5cc671e
--- /dev/null
+++ b/_contrib/CODE_STYLE.md
@@ -0,0 +1,26 @@
+---
+title: Code Style
+layout: guide
+hyper_path: docs/CODE_STYLE.md
+---
+
+hyper uses the default configuration of `rustfmt`.
+
+## cargo fmt
+
+`cargo fmt --all` does not work in hyper. Please use the following commands:
+
+```txt
+# Mac or Linux
+rustfmt --check --edition 2021 $(git ls-files '*.rs')
+
+# Powershell
+Get-ChildItem . -Filter "*.rs" -Recurse | foreach { rustfmt --check --edition 2021 $_.FullName }
+```
+
+> **NOTE**: If you are using `rust-analyzer`, you can add the following two lines in your `settings.json` to make sure the features get taken into account when checking the project:
+>
+>    ```json
+>     "rust-analyzer.cargo.features": ["full"],
+>     "rust-analyzer.check.features": ["full"],
+>    ```
diff --git a/_contrib/COMMITS.md b/_contrib/COMMITS.md
new file mode 100644
index 0000000..0b1f4e9
--- /dev/null
+++ b/_contrib/COMMITS.md
@@ -0,0 +1,69 @@
+---
+title: Git Commit Guidelines
+layout: guide
+hyper_path: docs/COMMITS.md
+---
+
+We have very precise rules over how our git commit messages can be formatted.  This leads to **more
+readable messages** that are easy to follow when looking through the **project history**.  But also,
+we use the git commit messages to **generate the change log**.
+
+## Commit Message Format
+Each commit message consists of a **header**, a **body** and a **footer**.  The header has a special
+format that includes a **type**, a **scope** and a **subject**:
+
+```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
+to read on github as well as in various git tools.
+
+## Type
+Must be one of the following:
+
+* **feat**: A new feature
+* **fix**: A bug fix
+* **docs**: Documentation only changes
+* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
+  semi-colons, etc)
+* **refactor**: A code change that neither fixes a bug or adds a feature
+* **perf**: A code change that improves performance
+* **test**: Adding missing tests
+* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
+    generation
+
+## Scope
+The scope should refer to a module in hyper that is being touched. Examples:
+
+* client
+* server
+* http1
+* http2
+* ffi
+* upgrade
+* examples
+
+## Subject
+
+The subject contains succinct description of the change:
+
+* use the imperative, present tense: "change" not "changed" nor "changes"
+* don't capitalize first letter
+* no dot (.) at the end
+
+## Body
+
+Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes"
+The body should include the motivation for the change and contrast this with previous behavior.
+
+## Footer
+
+The footer should contain any information about **Breaking Changes** and is also the place to
+reference GitHub issues that this commit **Closes**.
+
+The last line of commits introducing breaking changes should be in the form `BREAKING CHANGE: <desc>`
diff --git a/_contrib/CONTRIBUTING.md b/_contrib/CONTRIBUTING.md
new file mode 100644
index 0000000..8e39f75
--- /dev/null
+++ b/_contrib/CONTRIBUTING.md
@@ -0,0 +1,45 @@
+---
+title: Contributing to Hyper
+layout: guide
+hyper_path: CONTRIBUTING.md
+---
+
+You want to contribute? You're awesome!
+
+Contributions come in all shapes and sizes. Let's take a tour of some of the different wants you could contribute.
+
+## [Code of Conduct](code-of-conduct.md)
+
+Firstly, all interactions with the project need to abide by the code of conduct. This is to make sure everyone is treated kindly.
+
+## [Issues](issues.md)
+
+- **Filing an issue** is a contribution. We appreciate you letting us know about bugs you've found, and any information that you can provide that we can use to make hyper better. Without your filing it, we may not be aware of the bug.
+- [Triaging issues](issues.md#triaging) is a huge help. By your helping make issues better, the reporters can get answers sooner, and others can fix them with less effort. You can also volunteer as a frequent [triager](maintainers.md#triagers).
+- Discuss [feature requests][feat] (especially those marked [request-for-comment][b-rfc]).
+
+[feat]: https://github.com/hyperium/hyper/issues?q=is%3Aissue+is%3Aopen+label%3AC-feature
+[b-rfc]: https://github.com/hyperium/hyper/issues?q=is%3Aissue+is%3Aopen+label%3AB-rfc
+
+
+## [Pull Requests](pull-requests.md)
+
+By the way, consider checking the [list of easy issues](https://github.com/hyperium/hyper/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy) if you want to submit something.
+
+- [Submitting a Pull Request](pull-requests.md#submitting-a-pull-request)
+- [Commit Guidelines](commits.md)
+
+## Documentation
+
+Improving hyper's documentation is a huge help for everyone who is trying to _use_ hyper.
+
+- The API documentation (rendered at https://docs.rs/hyper) is stored as rustdoc comments directly in the source.
+- The main website has [tutorial-style guides](https://hyper.rs/guides). As of v1, they are currently in a [revamp](https://github.com/hyperium/hyper/issues/3411), and would greatly benefit from being filled out.
+
+## Help
+
+Helping others use hyper in their specific workflows is a very valuable way to contribute.
+
+- Answer questions asked directly in hyper's [Discussions](https://github.com/hyperium/hyper/discussions).
+- Join our [Discord](https://discord.gg/kkwpueZ) and help those who show up with questions.
+- **Blog about hyper.** You writing a blog post about how you use hyper to do something specific, or how you contributed a new feature, or debugged something in it, is a great idea. Not all examples can fit in the hyper repo. Search engines will help people find their use cases on your blog. And you can describe processes in more depth or from a different perspective.
diff --git a/_contrib/GOVERNANCE.md b/_contrib/GOVERNANCE.md
new file mode 100644
index 0000000..8e51d79
--- /dev/null
+++ b/_contrib/GOVERNANCE.md
@@ -0,0 +1,115 @@
+---
+title: Governance
+layout: guide
+hyper_path: docs/GOVERNANCE.md
+---
+
+## Making decisions
+
+There's two main pieces to the way decisions are made in hyper:
+
+1. A decision-making framework
+2. The people who apply it
+
+The people are described [lower down in this document](#roles).
+
+### Decision-making framework
+
+We start with the users. The project wouldn't exist without them, and it exists
+in order to enable users to do amazing things with HTTP. We listen to our
+users. Some actively contribute their thoughts, but many others we must seek
+out to learn about their usage, joys, and headaches. Those insights allow our
+experts to determine the best solutions for the users.
+
+We then define a set of [tenets](./tenets.md), which are guiding principles
+that can be used to measure aspects of individual decisions. It should be
+possible to identify one or more tenets that apply to why a decision is made.
+And the set helps us balance which priorities are more important for our users.
+
+We combine the usecases with the tenets to come up with a [vision](./vision.md)
+that provides a longer-term plan of what hyper _should_ look like.
+
+Finally, we define a [roadmap](./roadmap.md) that describes what the
+short-term, tactical changes to bring hyper closer in line with the vision.
+
+## Roles
+
+These are the roles people can fill when participating in the project. A list
+of the people in each role is available in [maintainers](./maintainers.md).
+
+### Contributor
+
+A contributor is anyone who contributes their time to provide value for the
+project. This could be in the form of code, documentation, filing issues,
+discussing designs, or helping others on the issue tracker or in chat.
+
+All contributors MUST follow the [Code of Conduct][coc].
+
+👋  **New here?** [This could be you!][contrib]
+
+
+### Triager
+
+Triagers assess issues on the issue tracker. They help make sure the work is
+well organized, and are critical for making new issue reporters feeling
+welcome.
+
+Responsibilities:
+
+- Adhere to the [Code of Conduct][coc]
+- Follow the [triager's guide][triage-guide]
+
+Privileges:
+
+- Can edit, label, and close issues
+- Member of the organization
+- Can be assigned issues and pull requests
+
+How to become:
+
+- Make a few [contributions][contrib] to the project, to show you can follow
+  the [Code of Conduct][coc].
+- Self-nominate by making a pull request adding yourself to the
+  [list](./maintainers.md#triagers).
+
+
+### Collaborator
+
+Collaborators are contributors who have been helping out in a consistent basis.
+
+Responsibilities:
+
+- Be exemplars of the [Code of Conduct][coc]
+- Internalize the [vision](./vision.md)
+- Reviewing pull requests from other contributors
+- Provide feedback on proposed features and design documents
+- [Welcome new contributors][triage-guide]
+- Answer questions in issues and/or chat
+- Mentor contributors to become members
+
+Privileges:
+
+- Can review and merge pull requests
+- Can trigger re-runs of CI, and approve CI for first-time contributors
+- Can assign issues and pull requests to other organization members
+
+How to become:
+
+- Work at fulfilling the above responsibilities.
+- Any collaborator may nominate a contributor who has been around for some time
+  and is already filling the responsibilities.
+- Another collaborator must second the nomination.
+- If there are no objections, a maintainer will welcome the new collaborator.
+
+Don't be afraid to ask a collaborator for what you could work on to reach this
+goal!
+
+### Maintainer
+
+Maintainers are the project admins. Besides being a collaborator, they take care
+of house-keeping duties, help lead the direction, and have the final authority when
+required.
+
+[coc]: ./code-of-conduct.md
+[contrib]: ./contributing.md
+[triage-guide]: ./issues.md#triaging
diff --git a/_contrib/ISSUES.md b/_contrib/ISSUES.md
new file mode 100644
index 0000000..ce3de69
--- /dev/null
+++ b/_contrib/ISSUES.md
@@ -0,0 +1,120 @@
+---
+title: Issues
+layout: guide
+hyper_path: docs/ISSUES.md
+---
+
+The [issue tracker][issues] for hyper is where we track all features, bugs, and discuss proposals.
+
+## Triaging
+
+Once an issue has been opened, it is normal for there to be discussion
+around it. Some contributors may have differing opinions about the issue,
+including whether the behavior being seen is a bug or a feature. This
+discussion is part of the process and should be kept focused, helpful, and
+professional.
+
+The objective of helping with triaging issues is to help reduce the issue
+backlog and keep the issue tracker healthy, while enabling newcomers another
+meaningful way to get engaged and contribute.
+
+### Acknowledge
+
+Acknowledge the human. This is meant actively, such as giving a welcome, or
+thanks for a detailed report, or any other greeting that makes the person feel
+that their contribution (issues are contributions!) is valued. It also is meant
+to be internalized, and be sure to always [treat the person kindly][COC]
+throughout the rest of the steps of triaging.
+
+### Ask for more info
+
+Frequently, we need more information than was originally provided to fully
+evaluate an issue.
+
+If it is a bug report, ask follow up questions that help us get a [minimum
+reproducible example][MRE]. This may take several round-trip questions. Once
+all the details are gathered, it may be helpful to edit the original issue text
+to include them all.
+
+### Categorize
+
+Once enough information has been gathered, the issue should be categorized
+with [labels](#labels). Ideally, most issues should be labelled with an area,
+effort, and severity. An issue _can_ have multiple areas, pick what fits. There
+should be only one severity, and the descriptions of each should help to pick
+the right one. The hardest label to select is "effort". If after reading the
+descriptions of each effort level, you're still unsure, you can ping a
+maintainer to pick one.
+
+### Adjust the title
+
+An optional step when triaging is to adjust the title once more information is
+known. Sometimes an issue starts as a question, and through discussion, it
+turns out to be a feature request, or a bug report. In those cases, the title
+should be changed from a question, and the title should be a succinct action to
+be taken. For example, a question about an non-existent configuration option
+may be reworded to "Add option to Client to do Zed".
+
+### Mentoring
+
+The last part of triaging is to try to make the issue a learning experience.
+After a discussion with the reporter, it would be good to ask if they are now
+interested in submitting the change described in the issue.
+
+Otherwise, it would be best to leave the issue with a series of steps for
+anyone else to try to write the change. That could be pointing out that a
+design proposal is needed, addressing certain points. Or, if the required
+changes are mostly know, a list of links to modules and functions where code
+needs to be changed, and to what. That way we mentor newcomers to become
+successful contributors of new [pull requests][PRs].
+
+## Labels
+
+Issues are organized with a set of labels. Most labels follow a system of being prefixed by a "type".
+
+### Area
+
+The area labels describe what part of hyper is relevant.
+
+- **A-body**: streaming request and response bodies.
+- **A-client**: the HTTP client.
+- **A-dependencies**: library dependencies.
+- **A-docs**: documentation.
+- **A-error**: error reporting and types.
+- **A-ffi**: the C API.
+- **A-http1**: the HTTP/1 specifics.
+- **A-http2**: the HTTP/2 specifics.
+- **A-server**: the HTTP server.
+- **A-tests**: the unit and integration tests.
+
+### Blocked
+
+These labels indicate an issue is "blocked" for some reason.
+
+- **B-breaking-change**: a breaking change that is waiting for the next semver-compatible release.
+- **B-rfc**: request for comments. More discussion is needed to explore the design.
+- **B-upstream**: waiting on something in a dependency or the compiler.
+
+### Category
+
+The category marks what kind of issue this is.
+
+- **C-bug**: something is wrong, this is bad!
+- **C-feature**: this is a new feature request, adding something new.
+- **C-performance**: make existing working code go faster.
+- **C-refactor**: improve internal code to help readability and maintenance.
+- **C-chore**: a general chore or maintenance task.
+
+### Effort
+
+The effort labels are a best-guess at roughly how much effort and knowledge of hyper is needed to accomplish the task.
+
+- **E-easy**: a great starting point for a new contributor.
+- **E-medium**: some knowledge of how hyper internals work would be useful.
+- **E-hard**: likely requires a deeper understanding of how hyper internals work.
+
+
+[issues]: https://github.com/hyperium/hyper/issues
+[COC]: ./code-of-conduct.md
+[PRs]: ./pull-requests.md
+[MRE]: https://en.wikipedia.org/wiki/Minimal_reproducible_example
diff --git a/_contrib/MAINTAINERS.md b/_contrib/MAINTAINERS.md
new file mode 100644
index 0000000..7d3a7e0
--- /dev/null
+++ b/_contrib/MAINTAINERS.md
@@ -0,0 +1,40 @@
+---
+title: The People
+layout: guide
+hyper_path: docs/MAINTAINERS.md
+---
+
+To see what these roles do, and how to become one, look at [governance](./governance.md).
+
+## Triagers
+
+- Eray Karatay (@programatik29)
+- Oddbjørn Grødem (@oddgrd)
+
+## Collaborators
+
+- Sean McArthur (@seanmonstar)
+- Steven Fackler (@sfackler)
+- Oliver Gould (@olix0r)
+- Eliza Weisman (@hawkw)
+- Lucio Franco (@LucioFranco)
+- Anthony Ramine (@nox)
+- David Pedersen (@davidpdrsn)
+- Adam Foltzer (@acfoltzer)
+- Noah Kennedy (@Noah-Kennedy)
+- dswij (@dswij)
+- tottoto (@tottoto)
+
+<details>
+<summary>Emeriti</summary>
+
+### Collaborator emeriti
+
+- Jonathan Reem (@reem)
+- Carl Lerche (@carllerche)
+
+</details>
+
+## Maintainers
+
+- Sean McArthur (@seanmonstar)
diff --git a/_contrib/MSRV.md b/_contrib/MSRV.md
new file mode 100644
index 0000000..856de49
--- /dev/null
+++ b/_contrib/MSRV.md
@@ -0,0 +1,13 @@
+---
+title: Minimum Support Rust Version (MSRV)
+layout: guide
+hyper_path: docs/MSRV.md
+---
+
+hyper's current policy is to always support a Rust version at least 6 months
+old. That is, a compiler version released within the last 6 months can compile
+hyper. It is possible that an older compiler can work, but that is not
+guaranteed. We try to increase the MSRV responsibly, only when a significant
+new feature is needed.
+
+The current MSRV is: **1.63**.
diff --git a/_contrib/PULL_REQUESTS.md b/_contrib/PULL_REQUESTS.md
new file mode 100644
index 0000000..d7567aa
--- /dev/null
+++ b/_contrib/PULL_REQUESTS.md
@@ -0,0 +1,53 @@
+---
+title: Pull Requests
+layout: guide
+hyper_path: docs/PULL_REQUESTS.md
+---
+
+Pull requests are the way to submit changes to the hyper repository.
+
+## Submitting a Pull Request
+
+In most cases, it a good idea to discuss a potential change in an
+[issue](issues.md). This will allow other contributors to provide guidance and
+feedback _before_ significant code work is done, and can increase the
+likelihood of getting the pull request merged.
+
+### Tests
+
+If the change being proposed alters code (as opposed to only documentation for
+example), it is either adding new functionality to hyper or it is fixing
+existing, broken functionality. In both of these cases, the pull request should
+include one or more tests to ensure that hyper does not regress in the future.
+
+### Commits
+
+Once code, tests, and documentation have been written, a commit needs to be
+made. Following the [commit guidelines](commits.md) will help with the review
+process by making your change easier to understand, and makes it easier for
+hyper to produce a valuable changelog with each release.
+
+However, if your message doesn't perfectly match the guidelines, **do not
+worry!** The person that eventually merges can easily fixup the message at that
+time.
+
+### Opening the Pull Request
+
+From within GitHub, open a new pull request from your personal branch.
+
+Once opened, pull requests are usually reviewed within a few days.
+
+### Discuss and Update
+
+You will probably get feedback or requests for changes to your Pull Request.
+This is a big part of the submission process so don't be discouraged! Some
+contributors may sign off on the Pull Request right away, others may have more
+detailed comments or feedback. This is a necessary part of the process in order
+to evaluate whether the changes are correct and necessary.
+
+Any community member can review a PR and you might get conflicting feedback.
+Keep an eye out for comments from code owners to provide guidance on
+conflicting feedback.
+
+You don't need to close the PR and create a new one to address feedback. You
+may simply push new commits to the existing branch.
diff --git a/_contrib/ROADMAP-1.0.md b/_contrib/ROADMAP-1.0.md
new file mode 100644
index 0000000..492fd87
--- /dev/null
+++ b/_contrib/ROADMAP-1.0.md
@@ -0,0 +1,410 @@
+---
+title: hyper 1.0 Roadmap
+layout: guide
+hyper_path: docs/ROADMAP-1.0.md
+---
+
+> This was the roadmap to arrive at hyper v1.0. It is kept for historical purposes. See [roadmap](./roadmap.md) for the latest.
+
+## Goal
+
+Align current hyper to the [hyper vision][vision].
+
+The vision outlines a decision-making framework, use-cases, and general shape
+of hyper. This roadmap describes the currently known problems with hyper, and
+then shows what changes are needed to make hyper 1.0 look more like what is in
+the vision.
+
+## Known Issues
+
+
+> **Note**: These known issues are as of hyper v0.14.x. After v1.0 is released,
+ideally these issues will have been solved. Keeping this history may be helpful
+to Future Us, though.
+
+### Higher-level Client and Server problems
+
+Both the higher-level `Client` and `Server` types have stability concerns.
+
+For the `hyper::Server`:
+
+- The `Accept` trait is complex, and too easy to get wrong. If used with TLS, a slow TLS handshake
+  can affect all other new connections waiting for it to finish.
+- The `MakeService<&IO>` is confusing. The bounds are an assault on the eyes.
+- The `MakeService` API doesn't allow to easily annotate the HTTP connection with `tracing`.
+- Graceful shutdown doesn't give enough control.
+
+
+It's more common for people to simply use `hyper::server::conn` at this point,
+than to bother with the `hyper::Server`.
+
+While the `hyper::Client` is much easier to use, problems still exist:
+
+- The whole `Connect` design isn't stable.
+  - ALPN and proxies can provide surprising extra configuration of connections.
+  - Some `Connect` implementations may wish to view the path, in addition to the scheme, host, and port.
+  - Wants `runtime` feature
+- The Pool could be made more general or composable. At the same time, more customization is
+  desired, and it's not clear
+how to expose it yet.
+
+
+### Runtime woes
+
+hyper has been able to support different runtimes, but it has sometimes awkward
+default support for Tokio.
+
+- The `runtime` cargo-feature isn't additive
+- Built-in Tokio support can be confusing
+- Executors and Timers
+  - The `runtime` feature currently enables a few options that require a timer, such as timeouts and
+    keepalive intervals. It implicitly relies on Tokio's timer context. This can be quite confusing.
+- IO traits
+  - Should we publicly depend on Tokio's traits?
+  - `futures-io`?
+    - Definitely nope.
+    - Not stable. (0.3?)
+    - No uninitialized memory.
+  - Eventual `std` traits?
+    - They've been in design for years.
+    - We cannot base our schedule on them.
+    - When they are stable, we can:
+      - Provide a bridge in `hyper-util`.
+      - Consider a 2.0 of hyper.
+  - Define our own traits, provide util wrappers?
+
+### Forwards-compatibility
+
+There's a concern about forwards-compatibility. We want to be able to add
+support for new HTTP features without needing a new major version. While most
+of `http` and `hyper` are prepared for that, there's two potential problems.
+
+- New frames on an HTTP stream (body)
+   - Receiving a new frame type would require a new trait method
+     - There's no way to implement a "receive unknown frame" that hyper doesn't know about.
+   - Sending an unknown frame type would be even harder.
+     - Besides being able to pass an "unknown" type through the trait, the user would need to be
+       able to describe how that frame is encoded in HTTP/2/3.
+- New HTTP versions
+  - HTTP/3 will require a new transport abstraction. It's not as simple as just using some
+    `impl AsyncRead + AsyncWrite`. While HTTP/2 bundled the concept of stream creation internally,
+    and thus could be managed wholly on top of a read-write transport, HTTP/3 is different. Stream
+    creation is shifted to the QUIC protocol, and HTTP/3 needs to be able to use that directly.
+  - This means the existing `Connection` types for both client and server will not be able to
+    accept a QUIC transport so we can add HTTP/3 support.
+
+### Errors
+
+It's not easy to match for specific errors.
+
+The `Error::source()` can leak an internal dependency. For example, a
+`hyper::Error` may wrap an `h2::Error`. Users can downcast the source at
+runtime, and hyper internally changing the version of its `h2` dependency can
+cause runtime breakage for users.
+
+Formatting errors is in conflict with the current expected norm. The
+`fmt::Display` implementation for `hyper::Error` currently prints its own
+message, and then prints the message of any wrapped source error. The Errors
+Working Group currently recommends that errors only print their own message
+(link?). This conflict means that error "reporters", which crawl a source chain
+and print each error, has a lot of duplicated information.
+
+```
+error fetching website: error trying to connect: tcp connect error: Connection refused (os error 61)
+tcp connect error: Connection refused (os error 61)
+Connection refused (os error 61)
+```
+
+While there is a good reason for why hyper's `Error` types do this, at the very
+least, it _is_ unfortunate.
+
+### You call hyper, or hyper calls you?
+
+> Note: this problem space, of who calls whom, will be explored more deeply in
+> a future article.
+
+At times, it's been wondered whether hyper should call user code, or if user
+code should call hyper. For instance, should a `Service` be called with a
+request when the connection receives one, or should the user always poll for
+the next request.
+
+There's a similar question around sending a message body. Should hyper ask the
+body for more data to write, or should the user call a `write` method directly?
+
+These both get at a root topic about [write
+observability](https://github.com/hyperium/hyper/issues/2181). How do you know
+when a response, or when body data, has been written successfully? This is
+desirable for metrics, or for triggering other side-effects. 
+
+The `Service` trait also has some other frequently mentioned issues. Does
+`poll_ready` pull its complexity weight for servers? What about returning
+errors, what does that mean? Ideally users would turn all errors into
+appropriate `http::Response`s. But in HTTP/2 and beyond, stream errors are
+different from HTTP Server Error responses. Could the `Service::Error` type do
+more to encourage best practices?
+
+## Design
+
+The goal is to get hyper closer to the [vision][], using that to determine the
+best way to solve the known issues above. The main thrust of the proposed
+changes are to make hyper more **Flexible** and stable.
+
+In order to keep hyper **Understandable**, however, the proposed changes *must*
+be accompanied by providing utilities that solve the common usage patterns,
+documentation explaining how to use the more flexible pieces, and guides on how
+to reach for the `hyper-util`ity belt.
+
+The majority of the changes are smaller and can be contained to the *Public
+API* section, since they usually only apply to a single module or type. But the
+biggest changes are explained in detail here.
+
+### Split per HTTP version
+
+The existing `Connection` types, both for the client and server, abstract over
+HTTP version by requiring a generic `AsyncRead + AsyncWrite` transport type.
+But as we figure out HTTP/3, that needs to change. So to prepare now, the
+`Connection` types will be split up.
+
+For example, there will now be `hyper::server::conn::http1::Connection` and
+`hyper::server::conn::http2::Connection` types.
+
+These specific types will still have a very similar looking API that, as the
+vision describes, provides **Correct** connection management as it pertains to
+HTTP.
+
+There will be still be a type to wrap the different versions. It will no longer
+be generic over the transport type, to prepare for being able to wrap HTTP/3
+connections. Exactly how it will wrap, either by using internal trait objects,
+or an `enum Either` style, or using a `trait Connection` that each type
+implements, is something to be determined. It's likely that this "auto" type
+will start in `hyper-util`.
+
+### Focus on the `Connection` level
+
+As mentioned in the *Known Issues*, the higher-level `Client` and `Server` have
+stability and complexity problems. Therefore, for hyper 1.0, the main API will
+focus on the "lower-level" connection types. The `Client` and `Server` helpers
+will be moved to `hyper-util`.
+
+## Public API
+
+### body
+
+The `Body` struct is removed. Its internal "variants" are [separated into
+distinct types](https://github.com/hyperium/hyper/issues/2345), and can start
+in either `hyper-util` or `http-body-util`.
+
+The exported trait `HttpBody` is renamed to `Body`.
+
+A single `Body` implementation in `hyper` is the one provided by receiving
+client responses and server requests. It has the name `Streaming`.
+
+> **Unresolved**: Other names can be considered during implementation. Another
+> option is to not publicly name the implementation, but return `Response<impl
+Body>`s.
+
+The `Body` trait will be experimented on to see about making it possible to
+return more frame types beyonds just data and trailers.
+
+> **Unresolved**: What exactly this looks like will only be known after
+> experimentation.
+
+### client
+
+The high-level `hyper::Client` will be removed, along with the
+`hyper::client::connect` module. They will be explored more in `hyper-util`.
+
+As described in *Design*, the `client::conn` module will gain `http1` and
+`http2` sub-modules, providing per-version `SendRequest`, `Connection`, and
+`Builder` structs. An `auto` version can be explored in `hyper-util`.
+
+### error
+
+The `hyper::Error` struct remains in place.
+
+All errors returned from `Error::source()` are made opaque. They are wrapped an
+internal `Opaque` newtype that still allows printing, but prevents downcasting
+to the internal dependency.
+
+A new `hyper::error::Code` struct is defined. It is an opaque struct, with
+associated constants defining various code variants.
+
+> Alternative: define a non-exhaustive enum. It's not clear that this is
+> definitely better, though. Keeping it an opaque struct means we can add
+> secondary parts to the code in the future, or add bit flags, or similar
+> extensions.
+
+The purpose of `Code` is to provide an abstraction over the kind of error that
+is encountered. The `Code` could be some behavior noticed inside hyper, such as
+an incomplete HTTP message. Or it can be "translated" from the underlying
+protocol, if it defines protocol level errors. For example, an
+`h2::Reason::CANCEL`.
+
+### rt
+
+The `Executor` trait stays in here.
+
+Define a new trait `Timer`, which describes a way for users to provide a source
+of sleeping/timeout futures. Similar to `Executor`, a new generic is added to
+connection builders to provide a `Timer`.
+
+### server
+
+The higher-level `hyper::Server` struct, its related `Builder`, and the
+`Accept` trait are all removed.
+
+The `AddrStream` struct will be completely removed, as it provides no value but
+causes binary bloat.
+
+Similar to `client`, and as describe in the *Design*, the `conn` modules will
+be expanded to support `http1` and `http2` submodules. An `auto` version can be
+explored in `hyper-util`.
+
+### service
+
+A vendored and simplified `Service` trait will be explored.
+
+The error type for `Service`s used for a server will explore having the return
+type changed from any error to one that can become a `hyper::error::Code`.
+
+> **Unresolved**: Both of the above points are not set in stone. We will
+> explore and decide if they are the best outcome during development.
+
+The `MakeService` pieces will be removed.
+
+### Cargo Features
+
+Remove the `stream` feature. The `Stream` trait is not stable, and we cannot
+depend on an unstable API.
+
+Remove the `tcp` and `runtime` features. The automatic executor and timer parts
+are handled by providing implementations of `Executor` and `Timer`. The
+`connect` and `Accept` parts are also moving to `hyper-util`.
+
+### Public Dependencies
+
+- `http`
+- `http-body`
+- `bytes`
+
+Cannot be public while "unstable":
+
+- `tracing`
+
+## `hyper-util`
+
+
+### body
+
+A channel implementation of `Body` that has an API to know when the data has
+been successfully written is provided in `hyper_util::body::channel`.
+
+### client
+
+A `Pool` struct that implements `Service` is provided. It fills a similar role
+as the previous `hyper::Client`.
+
+> **Note**: The `Pool` might be something that goes into the `tower` crate
+> instead. Or it might stay here as a slightly more specialized racing-connect
+> pool. We'll find out as we go.
+
+A `connect` submodule that mostly mirrors the existing `hyper::client::connect`
+module is moved here. Connectors can be used as a source to provide `Service`s
+used by the `Pool`.
+
+### rt
+
+We can provide Tokio-backed implementations of `Executor` and `Timer`.
+
+### server
+
+A `GracefulShutdown` helper is provided, to allow for similar style of graceful
+shutdown as the previous `hyper::Server` did, but with better control.
+
+# Appendix
+
+## Unresolved Questions
+
+There are some parts of the proposal which are not fully resolved. They are
+mentioned in Design and API sections above, but also collected here for easy
+finding. While they all have _plans_, they are more exploratory parts of the
+API, and thus they have a higher possibility of changing as we implement them.
+
+The goal is to have these questions resolved and removed from the document by
+the time there is a [Release Candidate][timeline].
+
+### Should there be `hyper::io` traits?
+
+Depending on `tokio` just for `AsyncRead` and `AsyncWrite` is convenient, but
+can be confusing for users integrating hyper with other runtimes. It also ties
+our version directly to Tokio. We can consider having vendored traits, and
+providing Tokio wrappers in `hyper-util`.
+
+### Should returned body types be `impl Body`?
+
+### How could the `Body` trait prepare for unknown frames?
+
+We will experiment with this, and keep track of those experiments in a
+dedicated issue. It might be possible to use something like this:
+
+```rust
+pub trait Body {
+    type Data;
+    fn poll_frame(..) -> Result<Option<Frame<Self::Data>>>;
+}
+
+pub struct Frame<T>(Kind<T>);
+
+enum Kind<T> {
+   Data(T),
+   Trailers(HeaderMap),
+   Unknown(Box<dyn FrameThingy>),
+}
+```
+
+### Should there be a simplified `hyper::Service` trait, or should hyper depend on `tower-service`?
+
+- There's still a few uncertain decisions around tower, such as if it should be
+  changed to `async fn call`, and if `poll_ready` is the best way to handle
+  backpressure.
+- It's not clear that the backpressure is something needed at the `Server`
+  boundary, thus meaning we should remove `poll_ready` from hyper.
+- It's not 100% clear if we should keep the service pattern, or use a
+  pull-based API. This will be explored in a future blog post.
+
+## FAQ
+
+### Why did you pick _that_ name? Why not this other better name?
+
+Naming is hard. We certainly should solve it, but discussion for particular
+names for structs and traits should be scoped to the specific issues. This
+document is to define the shape of the library API.
+
+### Should I publicly depend on `hyper-util`?
+
+The `hyper-util` crate will not reach 1.0 when `hyper` does. Some types and
+traits are being moved to `hyper-util`. As with any pre-1.0 crate, you _can_
+publicly depend on it, but it is explicitly less stable.
+
+In most cases, it's recommended to not publicly expose your dependency on
+`hyper-util`. If you depend on a trait, such as used by the moved higher-level
+`Client` or `Server`, it may be better for your users to define your own
+abstraction, and then make an internal adapter.
+
+### Isn't this making hyper harder?
+
+We are making hyper more **flexible**. As noted in the [vision][], most use
+cases of hyper require it to be flexible. That _can_ mean that the exposed API
+is lower level, and that it feels more complicated. It should still be
+**understandable**.
+
+But the hyper 1.0 effort is more than just the single `hyper` crate. Many
+useful helpers will be migrated to a `hyper-util` crate, and likely improved in
+the process. The [timeline][] also points out that we will have a significant
+documentation push. While the flexible pieces will be in hyper to compose how
+they need, we will also write guides for the [hyper.rs][] showing people how to
+accomplish the most common tasks.
+
+[timeline]: https://seanmonstar.com/post/676912131372875776/hyper-10-timeline
+[vision]: https://github.com/hyperium/hyper/pull/2772
+[hyper.rs]: https://hyper.rs
diff --git a/_contrib/ROADMAP.md b/_contrib/ROADMAP.md
new file mode 100644
index 0000000..081c392
--- /dev/null
+++ b/_contrib/ROADMAP.md
@@ -0,0 +1,115 @@
+---
+title: Roadmap
+layout: guide
+hyper_path: docs/ROADMAP.md
+---
+
+## Goal
+
+Align current hyper to the [hyper vision](./vision.md).
+
+The vision outlines a decision-making framework, use-cases, and general shape
+of hyper. This roadmap describes the focus areas to continue to improve hyper
+to look more like what is in the vision.
+
+## Focus Areas
+
+While open source is not a company, open source can be guiding. We _can_ focus
+attention to specific areas of improvement, which are based on conversations
+with users, and prioritized by frequency and impact.
+
+To that end, the following 4 areas are current focus of the project:
+
+1. Documentation
+2. `hyper-util`
+3. HTTP/3
+4. Observability
+
+Each area benefits from having a top level description and goal, a place to
+track progress, and a champion (or two) that helps push the effort.
+
+### Documentation
+
+hyper has stabilized, so investing in documentation is wise! The way it is used
+won't change much, so documentation won't become outdated quickly. A tool that
+people don't know how to use isn't helpful at all. This helps hyper be
+**Understandable**.
+
+The documentation focus area includes several different forms:
+
+- The API docs as a reference.
+- Examples as form of how-to.
+- Website guides as tutorials.
+
+Each of these could benefit from dedicated planning of their overall structure,
+editing the content that already exists, and creating the rest that is sorely
+missing.
+
+### hyper-util
+
+`hyper-util` serves two main purposes:
+
+1. Provide useful patterns that build on top of hyper.
+2. Explore, stabilize, and graduate some of those patterns into hyper itself.
+
+To that end, there are several new features that can be worked on and iterated
+on in `hyper-util` right now:
+
+- New design for a higher-level `Client`.
+- Breaking apart some patterns from `reqwest`, such as proxy helpers.
+- Server automatic version detection.
+- Improved builder patterns that make it easier to configure complicated
+  options.
+
+### HTTP/3
+
+hyper has an HTTP/3 crate, `h3`, that is generic over any QUIC implementation,
+similar to how hyper's HTTP/1 and HTTP/2 can be provided any IO transport. It
+supports much of HTTP/3 already, and interoperates with most other
+implementations. While some brave users have been trying it out the hard way
+(such as reqwest), it's time to bring HTTP/3 to more users.
+
+The aim is to eventually support `hyper::client::conn::http3` and
+`hyper::server::conn::http3`.
+
+To do so, work is needed:
+
+- Harden the `h3` crate itself, such as fixing any straggling interop issues,
+  and filling out the spec conformance tags we use for accountability.
+- Proposal for (initially unstable) `hyper::rt::quic` integration, allowing
+  people to bring their own QUIC.
+- Write the `hyper::proto::http3` glue that translates hyper's connection
+  patterns with the `h3` crate.
+
+### Observability
+
+It's extremely common once operating a service using hyper to want more
+visibility in what exactly is happening. It's important to realize that there
+are 3 concepts involved that frequently get conflated: events, tracing, and
+metrics.
+
+Some existing ways to get some of these:
+
+- Unstable `tracing` integraton inside hyper.
+- `tower_http::trace` which instruments outside of hyper, using `Service` and
+  `Body`.
+
+However, there are some events and metrics that are only known inside hyper,
+and having official, stable support would be very helpful.
+
+Some potential options would be:
+
+- Stabilizing specific `tracing` events (blocked on the `tracing` crate
+  stabilizing...)
+- Provide a rudimentary, programmatic way to query metrics without another
+  crate.
+- Provide some sort of `hyper-metrics` helper.
+
+## Beyond
+
+The above are focus areas that are the most frequently asked for, and so have
+the most attention. That doesn't mean that nothing else can be worked on.
+
+Motivated individuals that want to help make other improvements are certainly
+welcome!
+
diff --git a/_contrib/TENETS.md b/_contrib/TENETS.md
new file mode 100644
index 0000000..c037bf3
--- /dev/null
+++ b/_contrib/TENETS.md
@@ -0,0 +1,102 @@
+---
+title: Charter
+layout: guide
+hyper_path: docs/TENETS.md
+---
+
+> hyper is a protective and efficient HTTP library for all.
+
+# Tenets
+
+Tenets are guiding principles. They guide how decisions are made for the whole
+project. Ideally, we do all of them all the time. In some cases, though, we may
+be forced to decide between slightly penalizing one goal or another. In that
+case, we tend to support those goals that come earlier in the list over those
+that come later (but every case is different).
+
+## 0. Open
+
+hyper is open source, always. The success of hyper depends on the health of the
+community building and using it. All contributions are in the open. We don't
+maintain private versions, and don't include features that aren't useful to
+others.
+
+[We prioritize kindness](./code-of-conduct.md), compassion and empathy towards all
+contributors. Technical skill is not a substitute for human decency.
+
+### Examples
+
+It's not usually hard for an open source library to stay open and also meet its
+other priorities. Here's some instances where being **Open** would be more
+important than **Correct** or **Fast**:
+
+- Say an individual were to bring forward a contribution that makes hyper more
+  correct, or faster, perhaps fixing some serious bug. But in doing so, they
+  also insulted people, harassed other contributors or users, or shamed
+  everyone for the previous code. They felt their contribution was "invaluable".
+  We would not accept such a contribution, instead banning the user and
+  rewriting the code amongst the kind collaborators of the project.
+
+- Say someone brings a contribution that adds a new feature useful for
+  performance or correctness, but their work accomplishes this by integrating
+  hyper with a proprietary library. We would not accept such a contribution,
+  because we don't want such a feature limited only to those users willing to
+  compromise openness, and we don't want to bifurcate the ecosystem between those
+  who make that compromise and those who don't.
+
+## 1. Correct
+
+hyper is a memory safe and precise implementation of the HTTP specification.
+Memory safety is vital in a core Internet technology. Following the HTTP
+specifications correctly protects users. It makes the software durable to the
+“real world”. Where feasible, hyper enforces correct usage.
+
+This is more than just "don't write bugs". hyper actively protects the user.
+
+### Examples
+
+- Even though we follow the **HTTP/\*** specs, hyper doesn't blindly implement
+  everything without considering if it is safe to do so.
+
+## 2. Fast
+
+A fast experience delights users. A faster network library means a faster
+application, resulting in delighting our users’ users. Whether with one request,
+or millions.
+
+Being _fast_ means we improve throughput, drive down CPU usage, and improve
+sustainability.
+
+Fast _enough_. We don't sacrifice sanity for speed.
+
+## 3. HTTP/*
+
+hyper is specifically focused on HTTP. Supporting new HTTP versions is in scope,
+but supporting separate protocols is not.
+
+This also defines what the abstraction layer is: the API is designed around
+sending and receiving HTTP messages.
+
+## 4. Flexible
+
+hyper enables as many usecases as possible. It has no opinion on application
+structure, and makes few assumptions about its environment. This includes being
+portable to different operating systems.
+
+### Examples
+
+- While we choose safer defaults to be **Correct**, hyper includes options to
+  _allow_ different behavior, when the user requires them.
+- Providing choice usually makes things more complex, so being **Flexible** does
+  mean it's less _easy_. That can sometimes conflict with simplest way of making
+  hyper **Understandable**.
+
+## 5. Understandable
+
+hyper is [no more complicated than it has to
+be](https://en.wikipedia.org/wiki/Occam%27s_razor). HTTP is not simple. It may
+not be as "easy" as 1-line to do everything, but it shouldn't be "hard" to find
+the answers.
+
+From logical and misuse-resistant APIs, to stellar documentation, to transparent
+metrics.
diff --git a/_contrib/VISION.md b/_contrib/VISION.md
new file mode 100644
index 0000000..2810e95
--- /dev/null
+++ b/_contrib/VISION.md
@@ -0,0 +1,234 @@
+---
+title: hyper Vision
+layout: guide
+hyper_path: docs/VISION.md
+---
+
+## Purpose
+
+This is an overview of what the shape of hyper looks like, but also somewhat
+zoomed out, so that the _vision_ can survive while the exact minute details
+might shift and change over time.
+
+### Charter
+
+> hyper is a protective and efficient HTTP library for all.
+
+### Tenets
+
+Tenets are guiding principles. They guide how decisions are made for the whole
+project. Ideally, we do all of them all the time. In some cases, though, we may
+be forced to decide between slightly penalizing one goal or another. In that
+case, we tend to support those goals that come earlier in the list over those
+that come later (but every case is different).
+
+0. Open
+1. Correct
+2. Fast
+3. HTTP/\*
+4. Flexible
+5. Understandable
+
+There's a lot more detail about each in [tenets](./tenets.md).
+
+## Use Cases
+
+Who are the *users* of hyper? How would they use hyper?
+
+### Low-Level Client Library (curl, reqwest, aws-sdk)
+
+These client libraries care that hyper is **Flexible**, since they are
+expressing their own opinion on how a more-featured HTTP client should act.
+This includes opinions on connection establishment, management, pooling, HTTP
+version options, and even runtimes.
+
+curl's main reason for using hyper is that it is **Safe**.
+
+### Web Server Frameworks (deno, axum)
+
+These are using hyper's server feature to expose a different, higher-level API
+to users. Besides the obvious requirements, these require that hyper is
+**Fast**. Servers are costly, handling more requests faster is important to
+them.
+
+That hyper is **Flexible** is also important, in that it needs to be flexible
+enough for them to build a server framework, and allow them to express their
+own opinions about API to their users.
+
+### Services and Proxies (linkerd, cloudflare, fastly)
+
+These are using hyper directly, likely both the client and server, in order to
+build efficient and powerful services, applications, and tools for their end
+users. They care greatly that hyper is **Correct**, since web traffic can
+stretch the limits of what is valid HTTP, and exercise less-common parts of the
+specifications.
+
+They also require hyper to be **Fast**, for similar reasons that the web server
+frameworks do.
+
+### New Rust Web Developers
+
+These are developers who are either new to Rust, or new to web servers, and
+have reached for hyper to start with.
+
+It's likely that these users don't have strong opinions about how an HTTP
+server or client should work, just that it _should_ handle all the things they
+normally assume it would. For these users, it would be best to quickly help
+them compare their own expectations with hyper's capabilities, and may
+suggest reaching for higher-level, _easier_ libraries instead.
+
+Those that stick around after that recommendation are users that wish both to
+learn at a lower level, and to pick and choose what batteries they plug in to
+hyper as they move along. While they do care about the other tenets, that hyper
+is **Understandable** is of extra importance to them.
+
+## The Library
+
+So with all that context in mind, what does hyper, the library, actually look
+like? This doesn't highlight what _is_ and _isn't_ present. What currently
+needs to change to reach this vision is left to individual version roadmaps.
+
+### Layers
+
+In all cases, a user brings their own runtime and IO to work with hyper. The IO
+is provided to hyper, and hyper acts on top of it. hyper returns `Future`s that
+the user then decides how to poll, likely involving their runtime options.
+
+![architecture diagram](./vision-arch.svg)
+
+
+#### Protocol Codecs
+
+hyper has dedicated codecs for the major HTTP versions. Each is internally
+designed to be **Correct** and **Fast** when it comes to encoding and decoding.
+
+The individual codecs may be implemented as sub-crates, with a less-stable
+promise, to support the **Flexible** needs of some users who wish to build
+their own connection management, or customize encoding and decoding beyond what
+is officially supported.
+
+#### Connection State Management
+
+A **Correct** implementation includes more than just enforcing certain
+characters when encoding and decoding. Order of frames, and flags in certain
+frames can affect the state of the connection. Some examples of things enforced
+at this layer:
+
+- If a message has a `content-length`, enforce only that many bytes are read or
+  written.
+- Reading a `Response` before a `Request` is even written implies a mismatched
+  reply that should be interpreted as an error.
+- The presence of some headers, such as `Connection: close`, or the absence of
+  others, such as `content-length` and `transfer-encoding`, can mean that the
+  connection should terminate after the current message.
+- HTTP/2 and HTTP/3 may send connection-level frames that don't pertain to any
+  specific transaction, and must be read and handled regardless of if a user is
+  currently checking for a message.
+
+#### HTTP Role and Version Abstraction
+
+This is the public API layer. Methods exposed are around sending and receiving
+`http::Request`s and `http::Response`s, not around framing specifics of the
+different versions. These are built around a client or server `Connection`
+interface.
+
+By exposing this layer publicly, we take care of the **Correct** tenet, by not
+forcing the user to send the specific frames themselves. The API should be
+designed in a way that a user cannot easily (if at all) create an _incorrect_
+HTTP connection.
+
+Motivated by the **Flexible** tenet, there _are_ version-specific options that
+can be configured at this level, and version-specific functionality can usually
+be handled via `http::Extensions`.
+
+### Not quite stable, but utile (useful)
+
+Beyond what is directly in the hyper crate, there are useful (utile) parts that
+may not meet hyper's stability promise. Developing, experimenting, and exposing
+those parts is the purpose of the `hyper-util` crate. That crate does not have
+the same stability level as hyper. However, the goal is that things that other
+libraries might want to expose as a public dependency do not live in
+`hyper-util` forever, but rather stabilize and get promoted into `hyper`.
+
+Exactly what gets put into `hyper-util` presently is kept in the roadmap
+documents.
+
+### Stability Promise
+
+What even is hyper's stability promise? Does it mean we are "done"? No. Will we
+ever make breaking changes again? Probably. We'll still follow the [semantic
+versioning](https://semver.org).
+
+Prior to 1.0, hyper has already only done breaking changes once a year. So 1
+year isn't much of a promise. We'll have significant more use and understanding
+after a few years, and that could prompt some redesign.
+
+As of this writing, we'll promise that _major_ versions of hyper are stable for
+3 years. New features will come out in _minor_ versions frequently. If it is
+determined necessary to make breaking changes to the API, we'll save them for
+after the 3 years.
+
+hyper also establishes a Minimum Supported Rust Version (MSRV). hyper will
+support Rust versions at least 6 months old. If a new Rust version is released
+with a feature hyper wishes to use, we won't do so until at least 6 months
+afterwards. hyper will only ever require a new Rust version as a _minor_
+release (1.x), not as a patch (1.x.y).
+
+## Security
+
+The security of hyper is a large part of what makes hyper _protective_. We make
+hyper secure via the combined efforts of being **Correct**, focusing on
+**HTTP/\***, and making it all **Understandable**.
+
+### Memory Safety
+
+Being **Correct** requires that hyper be memory-safe. Using the Rust language
+gets us most of the way there. But there is the ability to write `unsafe`
+Rust. Does being **Correct** mean that we can _never_ write `unsafe` code
+anywhere? Even if it helps make hyper **Fast**? We can, carefully.
+
+How do we balance the two, so that hyper is secure?
+
+hyper prefers not to have large modules of intertwined `unsafe` code. hyper
+does allow small `unsafe` blocks, no more than a few lines, where it's easier
+to verify that the `unsafe` code was written **Correctly**.
+
+### Meticulous Testing
+
+hyper's test suite grows and grows. There's a lot that needs to be right.
+Parsers, encoders, state machines. When easily isolated, those pieces have
+internal unit tests. But hyper also keeps a large list of growing integration
+tests that make sure all the parts are **Correct**.
+
+Making writing new tests easy is a high priority. Investing in the testing
+infrastructure is a proven way to make sure hyper stays **Correct** and secure.
+
+### Constant Fuzzing
+
+One thing is to know specific cases to test for. But we can't know all the
+inputs or states that *might* cause a bug. That's why hyper has rounds of
+fuzzing built into its CI. It's also why hyper signs up for and uses resources
+to provide *constant*, around-the-clock fuzzing, always looking for something
+that hyper should be hardened against.
+
+### Security Process
+
+hyper has an outlined
+[SECURITY](https://github.com/hyperium/hyper/blob/master/SECURITY.md) process,
+so we can safely report and fix issues.
+
+## Non-goals
+
+After writing this up, it is easier to articulate what sorts of things many
+might associate with an HTTP library, but which are explicitly *not* for hyper.
+These are all things that are definitely **out of scope**.
+
+- TLS: We learned early that bundling TLS directly in hyper [has
+  problems](https://github.com/hyperium/hyper/issues/985). People also have
+  very strong opinions about which TLS implementation to use. The design of
+  hyper allows users to bring their own TLS.
+- Routing
+- Cookies
+- Not-HTTP: WebSockets, or other protocols that are built next to HTTP. It
+  should be possible to _use_ hyper to upgrade, but the actual next-protocol
+  should be handled by a different library.