From 3cd10e6e440ec319cf940941aaf5ebfda42cabf8 Mon Sep 17 00:00:00 2001 From: Facundo Farall <37149322+ffarall@users.noreply.github.com> Date: Mon, 23 Sep 2024 21:23:33 -0300 Subject: [PATCH 1/7] docs: :memo: Clarify firing of `import_notification_stream` in doc comment --- substrate/client/api/src/client.rs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/substrate/client/api/src/client.rs b/substrate/client/api/src/client.rs index 45cfafb25846..7101fdebdf98 100644 --- a/substrate/client/api/src/client.rs +++ b/substrate/client/api/src/client.rs @@ -65,9 +65,15 @@ pub trait BlockOf { pub trait BlockchainEvents { /// Get block import event stream. /// - /// Not guaranteed to be fired for every imported block, only fired when the node - /// has synced to the tip or there is a re-org. Use `every_import_notification_stream()` + /// Not guaranteed to be fired for every imported block. Use `every_import_notification_stream()` /// if you want a notification of every imported block regardless. + /// + /// This notification stream is fired... + /// - During initial sync process: if there is a re-org while importing blocks. See + /// [here](https://github.com/paritytech/substrate/pull/7118#issuecomment-694091901) for the + /// rationale behind this. + /// - After initial sync process: on every imported block, regardless of whether it is + /// the new best block or not, causes a re-org or not. fn import_notification_stream(&self) -> ImportNotifications; /// Get a stream of every imported block. From cfa0e45aed4f20bbda82990ad65303430b4377af Mon Sep 17 00:00:00 2001 From: Facundo Farall <37149322+ffarall@users.noreply.github.com> Date: Tue, 24 Sep 2024 10:25:59 -0300 Subject: [PATCH 2/7] Apply review suggestions Co-authored-by: Michal Kucharczyk <1728078+michalkucharczyk@users.noreply.github.com> --- substrate/client/api/src/client.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/substrate/client/api/src/client.rs b/substrate/client/api/src/client.rs index 7101fdebdf98..ef6f6c521b90 100644 --- a/substrate/client/api/src/client.rs +++ b/substrate/client/api/src/client.rs @@ -68,7 +68,7 @@ pub trait BlockchainEvents { /// Not guaranteed to be fired for every imported block. Use `every_import_notification_stream()` /// if you want a notification of every imported block regardless. /// - /// This notification stream is fired... + /// The events for this notification stream are emitted: /// - During initial sync process: if there is a re-org while importing blocks. See /// [here](https://github.com/paritytech/substrate/pull/7118#issuecomment-694091901) for the /// rationale behind this. From 60b35c97e13d1dd47b1aba4e9ac5d07e976e6acb Mon Sep 17 00:00:00 2001 From: Facundo Farall <37149322+ffarall@users.noreply.github.com> Date: Tue, 24 Sep 2024 12:12:14 -0300 Subject: [PATCH 3/7] docs: :memo: Add prdoc --- prdoc/pr_5811.prdoc | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 prdoc/pr_5811.prdoc diff --git a/prdoc/pr_5811.prdoc b/prdoc/pr_5811.prdoc new file mode 100644 index 000000000000..c6b3a83ad5a8 --- /dev/null +++ b/prdoc/pr_5811.prdoc @@ -0,0 +1,11 @@ +# Schema: Polkadot SDK PRDoc Schema (prdoc) v1.0.0 +# See doc at https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/prdoc/schema_user.json + +title: ... + +doc: + - audience: Node Dev + description: | + "Updates the doc comment on the `import_notification_stream` to make its behaviour clearer. Now it specifically states that this notification stream is fired on every import notification after the initial sync, and only when there are re-orgs in the initial sync." + +crates: [] From 2038461e1471a95fcb4737b6170a1ada1ce3236b Mon Sep 17 00:00:00 2001 From: Facundo Farall <37149322+ffarall@users.noreply.github.com> Date: Tue, 24 Sep 2024 12:18:29 -0300 Subject: [PATCH 4/7] docs: :memo: Include SemVer changes in prdoc --- prdoc/pr_5811.prdoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/prdoc/pr_5811.prdoc b/prdoc/pr_5811.prdoc index c6b3a83ad5a8..dfd050578804 100644 --- a/prdoc/pr_5811.prdoc +++ b/prdoc/pr_5811.prdoc @@ -8,4 +8,6 @@ doc: description: | "Updates the doc comment on the `import_notification_stream` to make its behaviour clearer. Now it specifically states that this notification stream is fired on every import notification after the initial sync, and only when there are re-orgs in the initial sync." -crates: [] +crates: + - name: sc-client-api + bump: minor From cf70c547a234a1c7ad00cc654dad6233bc92da3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20K=C3=B6cher?= Date: Tue, 24 Sep 2024 22:48:51 +0200 Subject: [PATCH 5/7] Update prdoc/pr_5811.prdoc --- prdoc/pr_5811.prdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/prdoc/pr_5811.prdoc b/prdoc/pr_5811.prdoc index dfd050578804..b1d068e26634 100644 --- a/prdoc/pr_5811.prdoc +++ b/prdoc/pr_5811.prdoc @@ -10,4 +10,4 @@ doc: crates: - name: sc-client-api - bump: minor + bump: patch From 15b22d9a892b310ee062c7301fac8642580913da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20K=C3=B6cher?= Date: Tue, 24 Sep 2024 22:50:43 +0200 Subject: [PATCH 6/7] Update prdoc/pr_5811.prdoc --- prdoc/pr_5811.prdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/prdoc/pr_5811.prdoc b/prdoc/pr_5811.prdoc index b1d068e26634..103fef4bb8b0 100644 --- a/prdoc/pr_5811.prdoc +++ b/prdoc/pr_5811.prdoc @@ -1,7 +1,7 @@ # Schema: Polkadot SDK PRDoc Schema (prdoc) v1.0.0 # See doc at https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/prdoc/schema_user.json -title: ... +title: "Improve `import_notification_stream` documentation" doc: - audience: Node Dev From cd812bfabd7e3525d2d70a94d55b573f79925f86 Mon Sep 17 00:00:00 2001 From: Facundo Farall <37149322+ffarall@users.noreply.github.com> Date: Tue, 24 Sep 2024 19:37:20 -0300 Subject: [PATCH 7/7] style: :art: Apply `cargo fmt` --- substrate/client/api/src/client.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/substrate/client/api/src/client.rs b/substrate/client/api/src/client.rs index ef6f6c521b90..764930984ed7 100644 --- a/substrate/client/api/src/client.rs +++ b/substrate/client/api/src/client.rs @@ -65,8 +65,9 @@ pub trait BlockOf { pub trait BlockchainEvents { /// Get block import event stream. /// - /// Not guaranteed to be fired for every imported block. Use `every_import_notification_stream()` - /// if you want a notification of every imported block regardless. + /// Not guaranteed to be fired for every imported block. Use + /// `every_import_notification_stream()` if you want a notification of every imported block + /// regardless. /// /// The events for this notification stream are emitted: /// - During initial sync process: if there is a re-org while importing blocks. See