Merge branch '010_docs'

7 files changed, 87 insertions, 20 deletions

diff --git a/README.md b/README.md
index 924aec476..8654d30e3 100644
--- a/README.md
+++ b/README.md
@@ -56,16 +56,16 @@ We're not _aware_ of any critical security features missing in Arti; but
 however, since Arti is comparatively new software, you should probably be
 cautious about using it in production.
 
-There are no guarantees about API stability yet: if you write code
-that uses Arti, you should expect it to break with future versions.  If you
-write an a configuration file for Arti, it might stop working in the future.
+Now that Arti has reached version 0.1.0, we believe it is suitable for
+_experimental_ embedding within other Rust applications.  We will try to keep
+the API as exposed by the top-level `arti_client` crate more or less stable
+over time.  (We may have to break existing programs from time to time, but we
+will try not to do so without a very good reason. Either way, we will try to
+follow Rust's semantic versioning best practices.)
 
 ## Trying it out today
 
 Arti can act as a SOCKS proxy that uses the Tor network.
-It knows how to download directory
-information and how to load it from cache, but it doesn't try to
-download more than one directory per run.
 
 To try it out, run the demo program in `arti` as follows.  It will open a
 SOCKS proxy on port 9150.
@@ -121,17 +121,18 @@ get our project manager to sign off on them.
    * [x] Performance: preemptive circuit construction
    * [x] Performance: circuit build timeout inference
    * [x] API support for embedding
-   * [ ] API support for status reporting
+   * [x] API support for status reporting
    * [x] Correct timeout behavior
    * [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/7)
 
  * Arti 1.0.0: Initial stable release (Goal: Mid September, 2022??)
    * Target audience: **initial users**
-   * [ ] Security audit
    * [ ] Stable API
    * [ ] Stable CLI
    * [ ] Stable configuration format
    * [ ] Automatic detection and response of more kinds of network problems
+   * [ ] At least as secure as C Tor
+   * [ ] Client performance similar to C Tor
    * [ ] More performance work
    * [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/8)
 
diff --git a/crates/arti-client/src/config.rs b/crates/arti-client/src/config.rs
index 1f3bf7862..9344773bc 100644
--- a/crates/arti-client/src/config.rs
+++ b/crates/arti-client/src/config.rs
@@ -282,8 +282,14 @@ impl From<SystemConfig> for SystemConfigBuilder {
 /// Finally, you can get fine-grained control over the members of a a
 /// TorClientConfig using [`TorClientConfigBuilder`].
 ///
-/// NOTE: These are NOT the final options or their final layout.
-/// Expect NO stability here.
+/// # ⚠ Stability Warning ⚠
+///
+/// The design of this structure, and of the configuration system for
+/// Arti, is likely to change significantly before the release of Arti
+/// 1.0.0. The layout of options within this structure is also likely
+/// to change. For more information see ticket [#285].
+///
+/// [#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct TorClientConfig {
     /// Information about the Tor network we want to connect to.
diff --git a/crates/arti-client/src/lib.rs b/crates/arti-client/src/lib.rs
index 79d6728b9..9169d9d31 100644
--- a/crates/arti-client/src/lib.rs
+++ b/crates/arti-client/src/lib.rs
@@ -15,11 +15,18 @@
 //!
 //! Note that Arti is a work in progress; although we've tried to write all the
 //! critical security components, you probably shouldn't use Arti in production
-//! until it's a bit more mature.
-//!
-//! Also note that all of the APIs for this crate, and for Arti in general, are
-//! not the least bit stable.  If you use this code, please expect your software
-//! to break on a regular basis.
+//! until it's a bit more mature.  (That said, now is a _great_ time to try
+//! our Arti on an experimental basis, so you can tell us what we need
+//! to fix between now and the 1.0.0 release.)
+//!
+//! Also note that the APIs for this crate are not all yet
+//! completely stable.  We'll try not to break things without good
+//! reason, and we'll follow semantic versioning when we do, but
+//! please expect a certain amount of breakage between now and 1.0.0.
+//!
+//! The APIs exposed by lower-level crates in Arti are _even more
+//! unstable_; they will break more often than those from
+//! `arti-client`, for less reason.
 //!
 //! # Using `arti-client`
 //!
diff --git a/crates/arti-config/src/lib.rs b/crates/arti-config/src/lib.rs
index 07b5a89cf..829546ddc 100644
--- a/crates/arti-config/src/lib.rs
+++ b/crates/arti-config/src/lib.rs
@@ -8,6 +8,14 @@
 //!
 //! It provides a client configuration tool using using `serde` and `config`,
 //! plus extra features defined here for convenience.
+//!
+//! # ⚠ Stability Warning ⚠
+//!
+//! The design of this crate, and of the configuration system for
+//! Arti, is likely to change significantly before the release of Arti
+//! 1.0.0.  For more information see ticket [#285].
+//!
+//! [#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285
 
 #![deny(missing_docs)]
 #![warn(noop_method_call)]
diff --git a/crates/tor-config/src/lib.rs b/crates/tor-config/src/lib.rs
index cbb2f6d1d..056502059 100644
--- a/crates/tor-config/src/lib.rs
+++ b/crates/tor-config/src/lib.rs
@@ -7,6 +7,14 @@
 //! implement [Tor](https://www.torproject.org/) in Rust.
 //!
 //! It provides low-level types for handling configuration values.
+//!
+//! # ⚠ Stability Warning ⚠
+//!
+//! The design of this crate, and of the configuration system for
+//! Arti, is likely to change significantly before the release of Arti
+//! 1.0.0.  For more information see ticket [#285].
+//!
+//! [#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285
 
 #![deny(missing_docs)]
 #![warn(noop_method_call)]
diff --git a/doc/Architecture.md b/doc/Architecture.md
index 974768e85..476a9c199 100644
--- a/doc/Architecture.md
+++ b/doc/Architecture.md
@@ -33,6 +33,9 @@ various ways.  Other crates should use this crate, and not actually
 use any crypto implementation crates directly.  (It's okay to use crates that
 define cryptographic traits.)
 
+`tor-error`: Declare a general `ErrorKind` implementation used to hide the
+details for the errors in higher-level Arti crates.
+
 `tor-persist`: Types and traits for handling persistent data in Arti.
 
 `tor-rtcompat`: Traits to expose a common interface for asynchronous runtime
@@ -96,8 +99,17 @@ network view as an instance of `tor-netdir::NetDir`.
 `arti-client`: A client library that can be used to connect to the Tor network
 and make connections.
 
+`arti-config`: Support for working with Arti's configuration file format.
+This is likely to move to a lower level and get refactored significantly
+before Arti 1.0.0.
+
 `arti`:  A simple command-line client program that can run as a SOCKS proxy.
 
+`arti-bench`: A testing crate for running performance tests.
+
+`arti-hyper`: An example crate, using `arti_client` as a backend for the
+`hyper` HTTP library.
+
 ## Design considerations, privacy considerations.
 
 As we build the APIs for Arti, we've been aiming for
diff --git a/doc/FAQ.md b/doc/FAQ.md
index 7e2004638..8d1552425 100644
--- a/doc/FAQ.md
+++ b/doc/FAQ.md
@@ -10,12 +10,37 @@ Arti is also the name of the software produced by this project.
 
 ## What is the status of Arti today?
 
-As of mid-June 2021: Arti ready for developers to play around with, but it is
-not yet ready for general use.  Arti can run as a simple Tor client and
-send anonymized traffic over the network; it has no support for running as a
-relay or for using onion services.
+As of March 2022: Arti is ready for experimental use by developers
+interesting in embedding Tor support in their projects.  Arti can run as
+a simple Tor client and send anonymized traffic over the network, but it
+has no support for running as a relay or for using onion services.
+
+Before Arti is ready for production use, we need to make sure that it
+has all the important security features from the C Tor implementation; we
+need to improve its performance; and we need to improve its APIs based
+on user requirements.  We hope to have this done for our
+[our 1.0.0 milestone](https://gitlab.torproject.org/tpo/core/arti/-/milestones/8#tab-issues) in September 2022.
+
+(After that, our 1.1 milestone will focus on anticensorship work,
+and 1.2 will focus on support for onion services.)
 
 ## Should I use Arti?
 
-As of mid-October 2021: only if you are interested in helping us find bugs!
+As of March 2022: You should only use Arti as a client if you are
+interesting in helping us experiment and find bugs.
+
+If you are interested in shipping Arti as part of your own application,
+you should start experimenting with it _now_, so that you can let us
+know what features and APIs are missing for you, and we have a chance to
+add them.
+
+## Will Arti replace the C Tor implementation?
+
+Eventually, yes.  But it will take a _lot_ of work.
+
+We plan to maintain and support the C Tor implementation until Arti is a
+viable replacement for the vast majority of use cases.  We estimate that
+this will take us several more years, at the least.  Even then, we plan
+to continue supporting the C Tor implementation for some while, to give
+people time to switch.