MINOR:Upgrade guide updates for KIP-479 #7550

bbejeck · 2019-10-17T20:59:47Z

More detailed description of your change,
if necessary. The PR title and PR message become
the squashed commit message, so use a separate
comment to ping reviewers.

Summary of testing strategy (including rationale)
for the feature or bug fix. Unit and/or integration
tests are expected for any behaviour change and
system tests should be considered for larger changes.

Committer Checklist (excluded from commit message)

Verify design and implementation
Verify test coverage and CI build status
Verify documentation (including upgrade notes)

bbejeck · 2019-10-17T21:00:47Z

ping @mjsax, @vvcephei, and @ableegoldman

\cc @JimGalasyn @londoncalling

ableegoldman

LGTM, left a few suggestions but feel free to take or leave any/all of them

ableegoldman · 2019-10-17T21:14:30Z

docs/streams/upgrade-guide.html

@@ -76,8 +76,13 @@ <h3><a id="streams_api_changes_240" href="#streams_api_changes_240">Streams API

    <!-- Placeholder KIP-213 -->
    <!-- Placeholder KIP-307 -->
-    <!-- Placeholder KIP-479 -->
+    <p>
+        Before the 2.4.0 version of Kafa Streams, users of the DSL could not name the state stores involved in a Stream-Stream join.  If users added DSL operations upstream of the 


nit: stream-stream join (or else KStream-KStream) here and below

ableegoldman · 2019-10-17T21:16:06Z

docs/streams/upgrade-guide.html


+        Another feature delivered by <code>StreamJoined</code> that will be of interest to users is that you can now configure the type of state store used in the join.  Users can now elect to use in-memory stores or custom state stores for a Stream-Stream join.  Users should note that the provided stores will not be available for searching via Interactive Queries.  With the addition of <code>StreamJoined</code> Stream-Stream join operations using <code>Joined</code> have been deprecated, and users are encouraged to switch over to Stream-Stream join methods using the new overloaded methods.  You can get more details from <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-479%3A+Add+StreamJoined+config+object+to+Join">KIP-479</a>


nits: (single line so can't refer to specific location)

"searching via IQ" -> "querying via IQ"?

The sentence beginning "With the addition..." reads a bit awkwardly to me. Maybe something like "stream-stream joins accepting a Joined parameter have been deprecated; users are encouraged to migrate to the new StreamJoined parameter (is that an accurate description?)

I would also maybe refactor the first sentence a bit, something like "With the addition of the StreamJoined object, you can now configure the type of state store..."

vvcephei

Thanks, @bbejeck.

As always, some wording nits are impossible to avoid, but it looks good to me overall!

vvcephei · 2019-10-18T15:25:30Z

docs/streams/upgrade-guide.html

@@ -76,8 +76,13 @@ <h3><a id="streams_api_changes_240" href="#streams_api_changes_240">Streams API

    <!-- Placeholder KIP-213 -->
    <!-- Placeholder KIP-307 -->
-    <!-- Placeholder KIP-479 -->
+    <p>
+        Before the 2.4.0 version of Kafa Streams, users of the DSL could not name the state stores involved in a Stream-Stream join.  If users added DSL operations upstream of the 


Suggested change

Before the 2.4.0 version of Kafa Streams, users of the DSL could not name the state stores involved in a Stream-Stream join. If users added DSL operations upstream of the

Before the 2.4.0 version of Kafa Streams, users of the DSL could not name the state stores involved in a Stream-Stream join. If users added DSL operations before the

Super subtle difference, but the only thing that affects the names is the order in which you call the DSL operators, so you can actually add upstream operations, as long as you add the new DSL calls after the original ones. I wouldn't get into it in the docs, but it's easy to swap "before" for "upstream" and be technically correct.

vvcephei · 2019-10-18T15:26:00Z

docs/streams/upgrade-guide.html

-    <!-- Placeholder KIP-479 -->
+    <p>
+        Before the 2.4.0 version of Kafa Streams, users of the DSL could not name the state stores involved in a Stream-Stream join.  If users added DSL operations upstream of the 
+        join, the internal names of the state stores would shift, requiring an application reset when redeploying.  Now in the 2.4.0 release Kafka Streams adds the <code>StreamJoined</code>


Suggested change

join, the internal names of the state stores would shift, requiring an application reset when redeploying. Now in the 2.4.0 release Kafka Streams adds the <code>StreamJoined</code>

join, the internal names of the state stores would shift, requiring an application reset when redeploying. In the 2.4.0 release, Kafka Streams adds the <code>StreamJoined</code>

vvcephei · 2019-10-18T15:31:35Z

docs/streams/upgrade-guide.html


+        Another feature delivered by <code>StreamJoined</code> that will be of interest to users is that you can now configure the type of state store used in the join.  Users can now elect to use in-memory stores or custom state stores for a Stream-Stream join.  Users should note that the provided stores will not be available for searching via Interactive Queries.  With the addition of <code>StreamJoined</code> Stream-Stream join operations using <code>Joined</code> have been deprecated, and users are encouraged to switch over to Stream-Stream join methods using the new overloaded methods.  You can get more details from <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-479%3A+Add+StreamJoined+config+object+to+Join">KIP-479</a>


Suggested change

Another feature delivered by <code>StreamJoined</code> that will be of interest to users is that you can now configure the type of state store used in the join. Users can now elect to use in-memory stores or custom state stores for a Stream-Stream join. Users should note that the provided stores will not be available for searching via Interactive Queries. With the addition of <code>StreamJoined</code> Stream-Stream join operations using <code>Joined</code> have been deprecated, and users are encouraged to switch over to Stream-Stream join methods using the new overloaded methods. You can get more details from <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-479%3A+Add+StreamJoined+config+object+to+Join">KIP-479</a>

Another feature delivered by <code>StreamJoined</code> is that you can now configure the type of state store used in the join. You can now elect to use in-memory stores or custom state stores for a Stream-Stream join. Note that the provided stores will not be available for searching via Interactive Queries. With the addition of <code>StreamJoined</code>, Stream-Stream join operations using <code>Joined</code> have been deprecated. Please switch over to Stream-Stream join methods using the new overloaded methods. You can get more details from <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-479%3A+Add+StreamJoined+config+object+to+Join">KIP-479</a>

Several suggestions for this line:

The audience of this documentation is the user, so it makes more sense to say "you" than "the user". If you look back over it, you'll see we mix both forms of address here and elsewhere. We should stick to "you", it's easier and more natural to read that way.

I also shortened up some phrases I felt were overly qualified.

bbejeck · 2019-10-18T20:44:28Z

\cc @mjsax

bbejeck · 2019-10-18T21:16:01Z

Thanks, @ableegoldman and @vvcephei for the review! I've updated per comments.

mjsax · 2019-10-18T23:32:39Z

docs/streams/upgrade-guide.html


+        Another feature delivered by <code>StreamJoined</code> is that you can now configure the type of state store used in the join.  You can now elect to use in-memory stores or custom state stores for a stream-stream join.  Note that the provided stores will not be available for querying via Interactive Queries.  With the addition of <code>StreamJoined</code>, stream-stream join operations using <code>Joined</code> have been deprecated. Please switch over to stream-stream join methods using the new overloaded methods.  You can get more details from <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-479%3A+Add+StreamJoined+config+object+to+Join">KIP-479</a>


Line too long...

mjsax · 2019-10-18T23:36:02Z

docs/streams/upgrade-guide.html

+    <p>
+        Before the 2.4.0 version of Kafa Streams, users of the DSL could not name the state stores involved in a stream-stream join.  If users added DSL operations before of the 
+        join, the internal names of the state stores would shift, requiring an application reset when redeploying.  In the 2.4.0 release, Kafka Streams adds the <code>StreamJoined</code>
+        object, which gives users the ability to name the join processor, repartition topic(s) (if a repartition is required), and the state stores involved in the join.  Also, by naming the state stores, the changelog topics backing the state stores are named as well.



Missing <br /> markup ?

Is it <br> or <br />? I've seen both in the docs and both seem to work, but what's the difference?

mjsax · 2019-10-21T22:34:31Z

docs/streams/upgrade-guide.html

-    <!-- Placeholder KIP-479 -->
+    <p>
+        Before the 2.4.0 version of Kafa Streams, users of the DSL could not name the state stores involved in a stream-stream join.  If users added DSL operations before of the 
+        join, the internal names of the state stores would shift, requiring an application reset when redeploying.  In the 2.4.0 release, Kafka Streams adds the <code>StreamJoined</code>


added DSL operations before of the join -- sound confusing.

If users changed their topology and added a operator before a join,

mjsax · 2019-10-21T22:35:06Z

docs/streams/upgrade-guide.html

+    <p>
+        Before the 2.4.0 version of Kafa Streams, users of the DSL could not name the state stores involved in a stream-stream join.  If users added DSL operations before of the 
+        join, the internal names of the state stores would shift, requiring an application reset when redeploying.  In the 2.4.0 release, Kafka Streams adds the <code>StreamJoined</code>
+        object, which gives users the ability to name the join processor, repartition topic(s) (if a repartition is required), and the state stores involved in the join.  Also, by naming the state stores, the changelog topics backing the state stores are named as well.


nit object -> class

line is still quite long.

mjsax · 2019-10-21T22:36:31Z

docs/streams/upgrade-guide.html

+        join, the internal names of the state stores would shift, requiring an application reset when redeploying.  In the 2.4.0 release, Kafka Streams adds the <code>StreamJoined</code>
+        object, which gives users the ability to name the join processor, repartition topic(s) (if a repartition is required), and the state stores involved in the join.  Also, by naming the state stores, the changelog topics backing the state stores are named as well.
+        <br/>
+        Another feature delivered by <code>StreamJoined</code> is that you can now configure the type of state store used in the join.  You can now elect to use in-memory stores or custom state stores for a stream-stream join.  Note that the provided stores will not be available for querying via Interactive Queries.  With the addition of <code>StreamJoined</code>, stream-stream join operations using <code>Joined</code> have been deprecated. Please switch over to stream-stream join methods using the new overloaded methods.  You can get more details from 


You can now elect -> You can elect (the now is repetitive as it's used in the sentence before already)

Also, this line is too long

Note that the provided stores will not be available for querying via Interactive Queries -> this is also true if the store in only named (might be worth to mention in the paragraph above already)?

mjsax · 2019-10-21T22:38:49Z

docs/streams/upgrade-guide.html

+        object, which gives users the ability to name the join processor, repartition topic(s) (if a repartition is required), and the state stores involved in the join.  Also, by naming the state stores, the changelog topics backing the state stores are named as well.
+        <br/>
+        Another feature delivered by <code>StreamJoined</code> is that you can now configure the type of state store used in the join.  You can now elect to use in-memory stores or custom state stores for a stream-stream join.  Note that the provided stores will not be available for querying via Interactive Queries.  With the addition of <code>StreamJoined</code>, stream-stream join operations using <code>Joined</code> have been deprecated. Please switch over to stream-stream join methods using the new overloaded methods.  You can get more details from 
+        <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-479%3A+Add+StreamJoined+config+object+to+Join">KIP-479</a>


nit. Missing . at the end of the sentence

mjsax · 2019-10-21T22:43:55Z

@bbejeck This needs to be rebased to resolve merged conflicts, too.

bbejeck · 2019-10-21T23:59:19Z

@mjsax updated and rebased this

Reviewers: A. Sophie Blee-Goldmann <sophie@confluent.io>, John Roesler <john@confluent.io>, Matthias J. Sax <matthias@confluent.io>

mjsax · 2019-10-22T00:28:29Z

Merged to trunk and cherry-picked to 2.4.

bbejeck added docs streams labels Oct 17, 2019

ableegoldman approved these changes Oct 17, 2019

View reviewed changes

vvcephei approved these changes Oct 18, 2019

View reviewed changes

mjsax reviewed Oct 18, 2019

View reviewed changes

mjsax reviewed Oct 21, 2019

View reviewed changes

bbejeck added 5 commits October 21, 2019 19:47

Upgrade guide updates for KIP-479

c4de471

Updated per comments

83fbeba

Changes for comments

a26bb09

break on line too long

bc0f1b1

MINOR: changes per comments

7c02c70

bbejeck force-pushed the MINOR-KIP-479_docs branch from c40204f to 7c02c70 Compare October 21, 2019 23:58

MINOR: fix html tag

352a9f6

mjsax merged commit c7a3d1b into apache:trunk Oct 22, 2019

mjsax pushed a commit that referenced this pull request Oct 22, 2019

MINOR:Upgrade guide updates for KIP-479 (#7550)

65dc4f3

Reviewers: A. Sophie Blee-Goldmann <sophie@confluent.io>, John Roesler <john@confluent.io>, Matthias J. Sax <matthias@confluent.io>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MINOR:Upgrade guide updates for KIP-479 #7550

MINOR:Upgrade guide updates for KIP-479 #7550

bbejeck commented Oct 17, 2019

bbejeck commented Oct 17, 2019

ableegoldman left a comment

ableegoldman Oct 17, 2019

bbejeck Oct 18, 2019

ableegoldman Oct 17, 2019

bbejeck Oct 18, 2019

vvcephei left a comment

vvcephei Oct 18, 2019

bbejeck Oct 18, 2019

vvcephei Oct 18, 2019

bbejeck Oct 18, 2019

vvcephei Oct 18, 2019

bbejeck Oct 18, 2019

bbejeck commented Oct 18, 2019

bbejeck commented Oct 18, 2019

mjsax Oct 18, 2019

mjsax Oct 18, 2019

ableegoldman Oct 19, 2019

bbejeck Oct 21, 2019

mjsax Oct 21, 2019

bbejeck Oct 21, 2019

mjsax Oct 21, 2019

mjsax Oct 21, 2019

bbejeck Oct 21, 2019

mjsax Oct 21, 2019

mjsax Oct 21, 2019

mjsax Oct 21, 2019

bbejeck Oct 21, 2019

mjsax commented Oct 21, 2019

bbejeck commented Oct 21, 2019

mjsax commented Oct 22, 2019


		Another feature delivered by <code>StreamJoined</code> that will be of interest to users is that you can now configure the type of state store used in the join. Users can now elect to use in-memory stores or custom state stores for a Stream-Stream join. Users should note that the provided stores will not be available for searching via Interactive Queries. With the addition of <code>StreamJoined</code> Stream-Stream join operations using <code>Joined</code> have been deprecated, and users are encouraged to switch over to Stream-Stream join methods using the new overloaded methods. You can get more details from <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-479%3A+Add+StreamJoined+config+object+to+Join">KIP-479</a>

	Before the 2.4.0 version of Kafa Streams, users of the DSL could not name the state stores involved in a Stream-Stream join. If users added DSL operations upstream of the
	Before the 2.4.0 version of Kafa Streams, users of the DSL could not name the state stores involved in a Stream-Stream join. If users added DSL operations before the

	join, the internal names of the state stores would shift, requiring an application reset when redeploying. Now in the 2.4.0 release Kafka Streams adds the <code>StreamJoined</code>
	join, the internal names of the state stores would shift, requiring an application reset when redeploying. In the 2.4.0 release, Kafka Streams adds the <code>StreamJoined</code>

MINOR:Upgrade guide updates for KIP-479 #7550

MINOR:Upgrade guide updates for KIP-479 #7550

Conversation

bbejeck commented Oct 17, 2019

Committer Checklist (excluded from commit message)

bbejeck commented Oct 17, 2019

ableegoldman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vvcephei left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bbejeck commented Oct 18, 2019

bbejeck commented Oct 18, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mjsax commented Oct 21, 2019

bbejeck commented Oct 21, 2019

mjsax commented Oct 22, 2019