[docs] Rewrite the docs for diff #4006
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Szelethus
added a commit
to Szelethus/codechecker
that referenced
this pull request
Sep 8, 2023
Despite only two lines of code, this patch is many things all in once: * We fix a bug where diffing tags returned unexpected (and percieved to be incorrect) results, * We redefine what we expect from diffing tags, * We redefine the expected heaviour around review status rules. Previously, we regarded review status rules are a timeless property, but what is even more true, we didn't really know what we expect from them when it came to diffing tags. This lead to confusion on the developer side and on the user side as well, and lead to whack-a-mole issues and patches like Ericsson#3675, that was more driven by what users expected from this feature than a comprehensive plan. This is okay -- the review status feature and the tag feature grew in their own world, and nobody can be faulted for being on top of these features having a very solid specifications right out of the gate. This patch solved this issue. From this point on, our stance is the following: when we diff runs, we always check whether a report is outstanding _at the time of the query_, and for diffing tags or timestamps, we check whether a report is outstanding _at the time of the tag/timestamp_. A user-facing documentation is written in Ericsson#4006, and can be previewed here: https://github.com/Szelethus/codechecker/blob/diff_docs_rewrite/docs/web/diff.md
Szelethus
force-pushed
the
diff_docs_rewrite
branch
from
d998d6e to
a7b04c2
Compare
Szelethus
added a commit
to Szelethus/codechecker
that referenced
this pull request
Sep 12, 2023
Despite only two lines of code, this patch is many things all in once: * We fix a bug where diffing tags returned unexpected (and percieved to be incorrect) results, * We redefine what we expect from diffing tags, * We redefine the expected heaviour around review status rules. Previously, we regarded review status rules are a timeless property, but what is even more true, we didn't really know what we expect from them when it came to diffing tags. This lead to confusion on the developer side and on the user side as well, and lead to whack-a-mole issues and patches like Ericsson#3675, that was more driven by what users expected from this feature than a comprehensive plan. This is okay -- the review status feature and the tag feature grew in their own world, and nobody can be faulted for being on top of these features having a very solid specifications right out of the gate. This patch solved this issue. From this point on, our stance is the following: when we diff runs, we always check whether a report is outstanding _at the time of the query_, and for diffing tags or timestamps, we check whether a report is outstanding _at the time of the tag/timestamp_. A user-facing documentation is written in Ericsson#4006, and can be previewed here: https://github.com/Szelethus/codechecker/blob/diff_docs_rewrite/docs/web/diff.md
Szelethus
force-pushed
the
diff_docs_rewrite
branch
from
a7b04c2 to
f8fb11b
Compare
Szelethus
added a commit
to Szelethus/codechecker
that referenced
this pull request
Sep 13, 2023
Despite only two lines of code, this patch is many things all in once: * We fix a bug where diffing tags returned unexpected (and percieved to be incorrect) results, * We redefine what we expect from diffing tags, * We redefine the expected heaviour around review status rules. Previously, we regarded review status rules are a timeless property, but what is even more true, we didn't really know what we expect from them when it came to diffing tags. This lead to confusion on the developer side and on the user side as well, and lead to whack-a-mole issues and patches like Ericsson#3675, that was more driven by what users expected from this feature than a comprehensive plan. This is okay -- the review status feature and the tag feature grew in their own world, and nobody can be faulted for being on top of these features having a very solid specifications right out of the gate. This patch solved this issue. From this point on, our stance is the following: when we diff runs, we always check whether a report is outstanding _at the time of the query_, and for diffing tags or timestamps, we check whether a report is outstanding _at the time of the tag/timestamp_. A user-facing documentation is written in Ericsson#4006, and can be previewed here: https://github.com/Szelethus/codechecker/blob/diff_docs_rewrite/docs/web/diff.md
cservakt
reviewed
Sep 18, 2023
Szelethus
force-pushed
the
diff_docs_rewrite
branch
from
f8fb11b to
c3dfd07
Compare
bruntib
approved these changes
Sep 23, 2023
bruntib
approved these changes
Sep 23, 2023
The previous docs were outdated, and recent patches specified more cornercase that were abscent. I decided to rewrite and exand on the diff docs. As I wrote more and more, it made sense to create a brand new file. The diff docs for specifically the GUI (https://github.com/Szelethus/codechecker/blob/diff_docs_rewrite/web/server/vue-cli/src/assets/userguide/userguide.md#compare-runs) seem to be a mess, but I'm not sure there is a need for rewriting, and if there is, I'm pretty sure it can wait a little :) Check out the final docs here: https://github.com/Szelethus/codechecker/blob/diff_docs_rewrite/docs/web/diff.md
Szelethus
force-pushed
the
diff_docs_rewrite
branch
from
b1e2b26 to
db21abb
Compare
Co-authored-by: bruntib <bruntib@users.noreply.github.com>
|
TODO: I linked my branch to the 6.23.0-rc1 release notes, that needs to point to the Ericsson/master branch after release. |
bruntib
requested changes
Dec 3, 2023
Szelethus
force-pushed
the
diff_docs_rewrite
branch
from
7004375 to
a050d5d
Compare
|
I fixed all the remaining comments. Unless there is factually wrong information found here, I strongly insist on finally landing this patch. Its already miles better than the current docs, and we can always make it prettier later down the line. |
bruntib
approved these changes
Jan 9, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I intend to squash these commits, but this is what I'd consider to be pretty close to the final version of the new diff docs.
As I wrote more and more, it made sense to create a brand new file. The diff docs for specifically the GUI (https://github.com/Szelethus/codechecker/blob/diff_docs_rewrite/web/server/vue-cli/src/assets/userguide/userguide.md#compare-runs) seem to be a mess, but I'm not sure there is a need for rewriting, and if there is, I'm pretty sure it can wait a little :)
Check out the final docs here: https://github.com/Szelethus/codechecker/blob/diff_docs_rewrite/docs/web/diff.md
Depends on #3995 and #3996.