[FLINK-26134][docs] Added table with Checkpoint/Savepoint guarantees …

[akalash]

…into documentation

What is the purpose of the change

Moved table with snapshot guarantees clarification from https://cwiki.apache.org/confluence/display/FLINK/FLIP-203%3A+Incremental+savepoints#FLIP203:Incrementalsavepoints-Proposal

Brief change log

• Added the table with snapshot guarantees

Verifying this change

it is documentation

Does this pull request potentially affect one of the following parts:

• Dependencies (does it add or upgrade a dependency): (yes / no)
• The public API, i.e., is any changed class annotated with @Public(Evolving): (yes / no)
• The serializers: (yes / no / don't know)
• The runtime per-record code paths (performance sensitive): (yes / no / don't know)
• Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: (yes / no / don't know)
• The S3 file system connector: (yes / no / don't know)

Documentation

• Does this pull request introduce a new feature? (yes / no)
• If yes, how is the feature documented? (not applicable / docs / JavaDocs / not documented)

[flinkbot]

Thanks a lot for your contribution to the Apache Flink project. I'm the @flinkbot. I help the community
to review your pull request. We will use this comment to track the progress of the review.

Automated Checks

Last check on commit 8b902f3 (Mon Feb 14 16:49:37 UTC 2022)

Warnings:

• Documentation files were touched, but no docs/content.zh/ files: Update Chinese documentation or file Jira ticket.

_{Mention the bot in a comment to re-run the automated checks.}

Review Progress

• ❓ 1. The [description] looks good.
• ❓ 2. There is [consensus] that the contribution should go into to Flink.
• ❓ 3. Needs [attention] from.
• ❓ 4. The change fits into the overall [architecture].
• ❓ 5. Overall code [quality] is good.

Please see the Pull Request Review Guide for a full explanation of the review process.

The Bot is tracking the review progress through labels. Labels are applied according to the order of the review items. For consensus, approval by a Flink committer of PMC member is required

Bot commands

The @flinkbot bot supports the following commands:

• @flinkbot approve description to approve one or more aspects (aspects: description, consensus, architecture and quality)
• @flinkbot approve all to approve all aspects
• @flinkbot approve-until architecture to approve everything until architecture
• @flinkbot attention @username1 [@username2 ..] to require somebody's attention
• @flinkbot disapprove architecture to remove an approval you gave earlier

[flinkbot]

CI report:

• 23011f4 Azure: FAILURE

Bot commands

The @flinkbot bot supports the following commands:

• @flinkbot run azure re-run the last Azure build

[akalash]

@infoverload, I need help with the design of this documentation. The idea is to have approximately the same table as here - https://cwiki.apache.org/confluence/display/FLINK/FLIP-203%3A+Incremental+savepoints#FLIP203:Incrementalsavepoints-Proposal.
So my questions:

• if you think that the background color makes sense here how I can do so? should I use HTML or I should do it in markdown?
• How correctly clarify the meaning of each line? Right now, I provide the cross-link to other pages where it was possible but I don't sure what to do with the rest ones - expanding definition directly in table or do it under the table.

[akalash]

@dawidwys, I have added the description to each table line under the table. I don't think that my clarification is perfect but it is all that I have. So if you have ideas on how to make it more clear, please, share them with me. Also, if you know doc pages to which I can link, give me know.

[smattheis]

I have left some comments as suggestions on how we could improve the referencing/integration into the rest of the docs.
The description of "Arbitrary job upgrad" and "Job upgrade w/o ..." weren't clear to me.

[infoverload]

I think expanding the definitions under the table is fine.

[Myasuka]

Thanks for creating this PR, I feel doubted about the description of relocatable native savepoint of current implementation.
I will also verify it later.

[akalash]

@dawidwys, what is the page with CLI documentation that you told about?

[dawidwys]

This is the cli page: https://nightlies.apache.org/flink/flink-docs-master/docs/deployment/cli/#creating-a-savepoint and this is a pending PR I mentioned: #18900

[smattheis]

@akalash Is it okay if I make some changes (commits) on top. I would try to correct some minor language issues which is cumbersome to do via review comments. Is that okay for you?

[akalash]

@smattheis, since the branch is from in my personal repository, it will be not convenient for you to add new commits on top. I think we usually use something like add a suggestion in PR for such things.

[smattheis]

I have made some suggestions which are just suggestions for better merging/integration of paragraphs. If I made it worse, please feel free to ignore.

[akalash]

@smattheis , I have not applied all of your suggestions but I have applied some of the ideas. So please, take a look again when you have time

[smattheis]

LGTM.

[dawidwys]

Are the values for Schema evolution correct?

[akalash]

I think yes, according to FLIP(https://cwiki.apache.org/confluence/display/FLINK/FLIP-203%3A+Incremental+savepoints#FLIP203:Incrementalsavepoints-Proposal) Canonical Savepoint is supported while all others are unofficially supported.

[dawidwys]

Haven't we said we want to either update it, or remove it from the current version of the table? @pnowojski

[pnowojski]

I don't remember. Have we?

[alpinegizmo]

It's going to be very helpful to have these details spelled out in the documentation.

I've provided some suggested fixups for the English -- some of which might introduce undesirable changes to the meaning, so please check them carefully.

And one overall note: I find it distracting that Checkpoint is often capitalized (even when it's not the first word in a sentence). I'd prefer use we use lowercase for checkpoints and savepoints, which I believe matches the style of the rest of the documentation.

[akalash]

@alpinegizmo , thanks a lot for your suggestions. I have made changes. Please, take a look once again when you have time.

[alpinegizmo]

Approving this now, but I noticed a few minor things that can be improved and offered suggestions for them.