CASSANDRA-18185 Accumulate all docs PR

[neshkeev]

I searched the entire repository for the *.md files and didn't spot any more of such typos.
Here is the command:

find . -not -path "./.git/*" -type f -name "*.md" -exec grep --color "\(\b\w\+\)\b\s*\1\b" {} \+

[neshkeev]

@smiklosovic , could you help me find someone who can merge the PR, please?

[smiklosovic]

Hi @neshkeev

thanks for the patch. I think it will be better if we put all doc-related changes together in one big patch and merge that one. It is not too much "effective" to merge this very tiny change. It would be way more preferable (from my point of view) to create a patch which would gather all docs fixes among pull requests and merge that one and we are ok for good.

I think there is a lot of docs PRs (if you filter them by "docs" tag), some of them might be obsolete and somebody would need to go through them.

[neshkeev]

I'll peruse the PRs with such a tag and try to combine them into a single one if possible.
Should I somehow include original authors of the PRs I'll combine into a single PR?

[smiklosovic]

Preferably.

You do that by specifying Co-authored-by: ... in the commit message.

[smiklosovic]

@neshkeev if you go through other PRs related to docs, ping me if you think it is not relevant anymore I will double check and we can close it.

[neshkeev]

@smiklosovic , I reviewed all the docs labeled PRs starting from #206 and joined them into a single commit here.

The following PRs weren't merged, because they are no longer relevant, either files were removed (completely, I tracked files that were renamed like *.rst -> *.adoc) or the fixes they proposed were already applied in different commits.

PRs that require attention:

#1655 - gen-nodetool-docs.py script is proposed to get changed in that PR
#589 - cqlsh.py script is proposed to get changed in that PR

PRs that can be safely closed without merging, because I merged them into this PR's commit:

#206
#359
#366
#390
#450
#567
#615
#618
#746
#974
#984
#1052
#1088
#1274
#1378
#1404
#1504
#1540
#1544
#1673
#1697
#1722
#1815
#1830
#1863
#1865
#1879
#2062

PRs that wasn't merged into this PR's commit, but still can be closed without merging:

#456 - a complex PR about data modeling, I wasn't sure I could merge it appropriately
#648 - already fixed in a different commit
#703 - already fixed in a different commit
#842 - the file has been removed
#888 - the file has been removed
#944 - already fixed in a different commit
#1073 - already fixed in a different commit
#1088 - the file has been removed
#1600 - already fixed in a different commit
#1808 - already fixed in a different commit
#1809 - already fixed in a different commit
#1810 - already fixed in a different commit
#1829 - already fixed in a different commit
#1861 - already fixed in a different commit
#1862 - already fixed in a different commit
#1864 - already fixed in a different commit
#1880 - already fixed in a different commit
#1943 - already fixed in a different commit

[michaelsembwever]

Generally LGTM.

But…
A more descriptive commit message please.
"Accumulate all docs PR" means nothing to me.

Something like "Accumulation of small typo fixes to docs" would be much better. Folk need to scan git history quickly.

I'm also not sure about the changes to hyphenation (coming from this PR). For example "open-source" just reads wrong to me (even when it's used as an adjective. The overall change to using hyphenation might need broader agreement. Personally I would just leave it out to move ahead with the other changes.

[neshkeev]

Those hyphenated adjectives looked odd to me too, when I was in doubt, I googled them, for example, open-source databases, or 5-node cluster

I agree with you, we need more input on this from the community to find out the best possible phrasing

[smiklosovic]

great work @neshkeev , I will take a closer look shortly.

[smiklosovic]

@neshkeev I believe PR 1073 is still relevant if you look closer.

[smiklosovic]

@neshkeev could you please specifically check this one? https://github.com/apache/cassandra/pull/1052/files#r1083818544

[smiklosovic]

I believe that #589 and #1655 can be worked on independently from this one. Especially if these patches are planning to be merged in various branches and this targets just trunk.

[smiklosovic]

@neshkeev great progress so far! what about cracking thought the rest after (or before) PR 206 as you mentioned?

[neshkeev]

what about cracking thought the rest after (or before) PR 206 as you mentioned?

Sorry, I didn't get that, could you, please rephrase it?

All the changes #206 proposes are included into this PR, or were fixed before me in different commits, only the impact -> impacts typo is left till now

[smiklosovic]

@neshkeev You wrote:

I reviewed all the docs labeled PRs starting from #206 and joined them into a single commit here.

So, it means that all PRs older than PR 206 (PRs 206 -> 1) are not reviewed yet ? If that is the case, could we review them all?

[neshkeev]

I should've emphasize it earlier: 206 is the first (chronologically) PR that is labeled with docs, there are no docs PRs before 206

[smiklosovic]

right ... so I think this is the last one as I put that comment there:

#180 (comment)

Thanks!

[smiklosovic]

@neshkeev could you please cherry-pick this?

instaclustr@2019411

I think we are in quite a good shape, I ll try to find somebody else to take a look too.

[Mmuzaf]

@neshkeev Please, consider the following typo fixes.
Mmuzaf@9445252

[smiklosovic]

I am not completely sure about these typos in java classes, they might probably go in as well but we should ask. It is categorically something different to commit "documentation" and "fix typos in sources".

[polandll]

There are some changes that should be made.

[neshkeev]

@smiklosovic , did you decide to do it differently?

[neshkeev]

@smiklosovic , please let me know why the PR got closed. I don't understand why it happened and how one can be helpful to the project.

[smiklosovic]

Hi @neshkeev , it was closed because we have committed the work into f27790c

Once the work has been done, we tend to close the accompanying PR as it just cease to have the reason of its existence.