meta: Draft a changelog and update docs/features (#228)

* Updates the main documentation.
* Renames the transport-related feature flags.
* Drafts a changelog highlighting the breaking changes.

Author: Swatinem

CHANGELOG.md

@@ -1,8 +1,43 @@
 # Changelog
 
+## Unreleased
+
+**Highlights**:
+
+The `sentry` crate has been split up into a `sentry-core`, and many smaller per-integration crates. Application users should continue using the `sentry` crate, but library users and integration/transport authors are encouraged to use the `sentry-core` crate instead.
+
+Additionally, sentry can now be extended via `Integration`s.
+
+**Breaking Changes**:
+
+- The `utils` module has been removed, and most utils have been moved into integrations.
+- The `integrations` module was completely rewritten.
+- When constructing a `Client` using a `ClientOptions` struct manually, it does not have any default integrations, and it does not resolve default options from environment variables any more. Please use the explicit `apply_defaults` function instead. The `init` function will automatically call `apply_defaults`.
+- The `init` function can’t be called with a `Client` anymore.
+
+**Features**:
+
+- Sentry can now capture `std::error::Error` types, using the `capture_error` and `Hub::capture_error` functions, and an additional `event_from_error` utility function.
+- Sentry now has built-in support to bind a `Hub` to a `Future`.
+- Sentry can now be extended with `Integration`s.
+- The `ClientInitGuard`, `Future` and `ScopeGuard` structs and `apply_defaults`, `capture_error`, `event_from_error`, `with_integration` and `parse_type_from_debug` functions have been added to the root exports.
+- The `FutureExt`, `Integration`, `IntoBreadcrumbs`, `IntoDsn`, `Transport` and `TransportFactory` traits are now exported.
+- The `types` module now re-exports `sentry-types`.
+
+**Deprecations**:
+
+- The `internals` module is deprecated. Please `use` items from the crate root or the `types` module instead.
+- All the feature flags have been renamed, the old names are still available but
+
+## 0.18.1
+
+- Fix potential segfault with `with_debug_meta` (#211).
+- Fix panic when running inside of tokio (#186).
+
 ## 0.18.0
 
 - Upgrade most dependencies to their current versions (#183):
+
   - `env_logger 0.7`
   - `reqwest 0.10`
   - `error-chain 0.12`

Makefile

@@ -40,7 +40,7 @@ test: checkall testall
 
 testfast:
 	@echo 'TESTSUITE'
-	cd sentry && cargo test --features=with_test_support
+	cd sentry && cargo test --features=test
 .PHONY: testfast
 
 testall:
@@ -73,24 +73,24 @@ check-no-default-features:
 
 check-failure:
 	@echo 'NO CLIENT + FAILURE'
-	@cd sentry && RUSTFLAGS=-Dwarnings cargo check --no-default-features --features 'with_failure'
+	@cd sentry && RUSTFLAGS=-Dwarnings cargo check --no-default-features --features 'failure'
 .PHONY: check-failure
 
 check-panic:
 	@echo 'NO CLIENT + PANIC'
-	@cd sentry && RUSTFLAGS=-Dwarnings cargo check --no-default-features --features 'with_panic'
+	@cd sentry && RUSTFLAGS=-Dwarnings cargo check --no-default-features --features 'panic'
 .PHONY: check-panic
 
 check-all-impls:
 	@echo 'NO CLIENT + ALL IMPLS'
-	@cd sentry && RUSTFLAGS=-Dwarnings cargo check --no-default-features --features 'with_failure,with_panic'
+	@cd sentry && RUSTFLAGS=-Dwarnings cargo check --no-default-features --features 'failure,panic'
 .PHONY: check-all-impls
 
 check-curl-transport:
 	@echo 'CURL TRANSPORT'
-	@cd sentry && RUSTFLAGS=-Dwarnings cargo check --features with_curl_transport
+	@cd sentry && RUSTFLAGS=-Dwarnings cargo check --features curl
 	@echo 'CURL TRANSPORT ONLY'
-	@cd sentry && RUSTFLAGS=-Dwarnings cargo check --no-default-features --features 'with_curl_transport,with_panic'
+	@cd sentry && RUSTFLAGS=-Dwarnings cargo check --no-default-features --features 'curl,panic'
 .PHONY: check-curl-transport
 
 check-actix:

sentry-actix/Cargo.toml

@@ -17,9 +17,8 @@ all-features = true
 [features]
 default = ["with_sentry_default"]
 with_sentry_default = [
-    "sentry/with_default_transport",
-    "sentry/with_panic",
-    "sentry/with_native_tls"
+    "sentry/transport",
+    "sentry/panic",
 ]
 
 [dependencies]

sentry-contexts/src/integration.rs

@@ -8,7 +8,9 @@ use crate::utils::{device_context, os_context, rust_context, server_name};
 
 /// Adds Contexts to Sentry Events.
 ///
-/// See https://develop.sentry.dev/sdk/event-payloads/contexts/
+/// See the [Contexts Interface] documentation for more info.
+///
+/// [Contexts Interface]: https://develop.sentry.dev/sdk/event-payloads/contexts/
 pub struct ContextIntegration {
     /// Add `os` context, enabled by default.
     pub add_os: bool,

sentry-contexts/src/lib.rs

@@ -4,7 +4,7 @@
 //! and `rust` contexts to Events, as well as sets a `server_name` if not
 //! already defined.
 //!
-//! See https://develop.sentry.dev/sdk/event-payloads/contexts/
+//! See the [Contexts Interface] documentation for more info.
 //!
 //! # Examples
 //!
@@ -15,6 +15,8 @@
 //! };
 //! let _sentry = sentry::init(sentry::ClientOptions::default().add_integration(integration));
 //! ```
+//!
+//! [Contexts Interface]: https://develop.sentry.dev/sdk/event-payloads/contexts/
 
 #![deny(missing_docs)]
 

sentry-core/src/lib.rs

@@ -20,7 +20,6 @@
 //! the concepts of [`Client`], [`Hub`] and [`Scope`], as well as the extension
 //! points via the [`Integration`], [`Transport`] and [`TransportFactory`] traits.
 //!
-//!
 //! # Minimal API
 //!
 //! By default, this crate comes with a so-called "minimal" mode. This mode will

sentry-core/src/macros.rs

@@ -55,21 +55,16 @@ macro_rules! with_client_impl {
 #[doc(hidden)]
 macro_rules! sentry_debug {
     ($($arg:tt)*) => {
-        #[cfg(feature = "client")] {
-            #[cfg(feature = "debug-logs")] {
-                ::log_::debug!(target: "sentry", $($arg)*);
-            }
-            #[cfg(not(feature = "debug-logs"))] {
-                $crate::Hub::with(|hub| {
-                    if hub.client().map_or(false, |c| c.options().debug) {
-                        eprint!("[sentry] ");
-                        eprintln!($($arg)*);
-                    }
-                });
-            }
+        #[cfg(feature = "debug-logs")] {
+            ::log_::debug!(target: "sentry", $($arg)*);
         }
-        #[cfg(not(feature = "client"))] {
-            let _ = ($($arg)*);
+        #[cfg(not(feature = "debug-logs"))] {
+            $crate::Hub::with(|hub| {
+                if hub.client().map_or(false, |c| c.options().debug) {
+                    eprint!("[sentry] ");
+                    eprintln!($($arg)*);
+                }
+            });
         }
     }
 }

sentry-types/CHANGELOG.md

@@ -6,8 +6,5 @@ pub mod v7;
 /// The latest version of the protocol.
 pub const LATEST: u16 = 7;
 
-/// The always latest sentry protocol version.
 #[cfg(feature = "protocol")]
-pub mod latest {
-    pub use super::v7::*;
-}
+pub use v7 as latest;

sentry-types/src/protocol/mod.rs

@@ -16,11 +16,7 @@ autoexamples = true
 all-features = true
 
 [features]
-default = ["client", "backtrace", "contexts", "failure", "panic", "transport"]
-
-# we still need a "client" feature, here, because `sentry_debug!` tests for that
-client = []
-debug-logs = ["log_", "sentry-core/debug-logs"]
+default = ["backtrace", "contexts", "failure", "panic", "transport"]
 
 # default integrations
 backtrace = ["sentry-backtrace"]
@@ -33,14 +29,20 @@ debug-images = ["sentry-debug-images"]
 error-chain = ["sentry-error-chain"]
 log = ["sentry-log"]
 slog = ["sentry-slog"]
-
 # other features
 test = ["sentry-core/test"]
-transport = ["with_default_transport"]
+debug-logs = ["log_", "sentry-core/debug-logs"]
+# transports
+transport = ["reqwest", "native-tls"]
+reqwest = ["reqwest_", "httpdate"]
+curl = ["curl_", "httpdate", "serde_json"]
+surf = ["surf_", "httpdate", "http-client", "futures"]
+native-tls = ["reqwest_/default-tls"]
+rustls = ["reqwest_/rustls-tls"]
 
 # deprecated feature flags, here for backwards compatibility, will be removed
 # at some point
-with_client_implementation = ["client"]
+with_client_implementation = []
 with_backtrace = ["backtrace"]
 with_failure = ["failure"]
 with_panic = ["panic"]
@@ -50,14 +52,12 @@ with_test_support = ["test"]
 with_debug_meta = ["debug-images"]
 with_device_info = ["contexts"]
 with_rust_info = ["contexts"]
-
-# transport related features, should be cleaned up further in the future
-with_default_transport = ["with_reqwest_transport", "with_native_tls"]
-with_reqwest_transport = ["reqwest", "httpdate", "with_client_implementation"]
-with_curl_transport = ["curl", "httpdate", "serde_json", "with_client_implementation"]
-with_surf_transport = ["surf", "httpdate", "http-client", "futures", "with_client_implementation"]
-with_rustls = ["reqwest/rustls-tls"]
-with_native_tls = ["reqwest/default-tls"]
+with_default_transport = ["transport"]
+with_reqwest_transport = ["reqwest"]
+with_curl_transport = ["curl"]
+with_surf_transport = ["surf"]
+with_native_tls = ["native-tls"]
+with_rustls = ["rustls"]
 
 [dependencies]
 sentry-core = { version = "0.18.0", path = "../sentry-core", features = ["client"] }
@@ -71,9 +71,9 @@ sentry-log = { version = "0.18.0", path = "../sentry-log", optional = true }
 sentry-panic = { version = "0.18.0", path = "../sentry-panic", optional = true }
 sentry-slog = { version = "0.18.0", path = "../sentry-slog", optional = true }
 log_ = { package = "log", version = "0.4.8", optional = true, features = ["std"] }
-reqwest = { version = "0.10.1", optional = true, features = ["blocking", "json"], default-features = false }
-curl = { version = "0.4.25", optional = true }
-surf = { version = "=2.0.0-alpha.3", optional = true }
+reqwest_ = { package = "reqwest", version = "0.10.1", optional = true, features = ["blocking", "json"], default-features = false }
+curl_ = { package = "curl", version = "0.4.25", optional = true }
+surf_ = { package = "surf", version = "=2.0.0-alpha.4", optional = true }
 http-client = { version = "3.0", optional = true }
 futures = { version = "0.3", optional = true }
 httpdate = { version = "0.3.2", optional = true }