docs cleanup

[slimreaper35]

Maintainers will complete the following section

• Commit messages are descriptive enough
• Code coverage from testing does not decrease and new code is covered
• Docs updated (if applicable)
• Docs links in the code are still valid (if docs were updated)

Note: if the contribution is external (not from an organization member), the CI
pipeline will not run automatically. After verifying that the CI is safe to run:

• approve GitHub Actions workflows by clicking a button
• approve the Red Hat Trusted App Pipeline container build by commenting /ok-to-test
  (as is the standard for Pipelines as Code)

[eskultety]

Since modifications are being done to the file, the PR feels a bit incomplete in that it's worth checking what information still applies, otherwise we'd be still publishing inaccurate and misleading data, which in essence, yes, was still completely wrong with the original file but was also kind of tolerable with the old cachito mentions since the file was inherently inaccurate as a whole; we should avoid that with its update/conversion to cachi2.
To support my argument a bit more, we also have this sentence in the doc:

"Cachi2 never executes your code, or the code of any of your dependencies. What about your build?"

Which in hindsight is a very bold statement in general, because hey, it's only ever going to be best effort given the inherently ever-present bugs :) and is also not true with Yarn v3 where we enabled the 'exec' plugin just to get some more essential plugins working with builds with the hope that it wouldn't ever lead to arbitrary code execution (which at the time of adding it wasn't the case, but who knows, maybe future versions of Yarn v3 will change that underneath without us even knowing...)

[slimreaper35]

Maybe I would throw away the whole section of package managers, and then we would need to edit the docs in 2 places, which it seems no one did, and that's why it stayed like that.

[eskultety]

Maybe I would throw away the whole section of package managers, and then we would need to edit the docs in 2 places, which it seems no one did, and that's why it stayed like that.

Sorry for not getting back. Yeah, agreed on the inconsistency. I still think there's value in explaining the background story, but we should maintain this information in the respective package manager's doc and only link to that piece of information from this document, do you agree?

@slimreaper35 can we reopen this? I don't think the discussion here should be abandoned.

[slimreaper35]

I also got an idea if it is not better to select the most relevant parts and put them in the main README.md. Contributors or users would get the background story straight away.

[eskultety]

I also got an idea if it is not better to select the most relevant parts and put them in the main README.md. Contributors or users would get the background story straight away.

That is also an acceptable option. Still, package manager related bits would still need to be moved to the respective docs.

Hmm, maybe not actually, maybe it could be all within README, just spread across multiple sections and linked together.

[slimreaper35]

There is also another outdated document that was copied from Cachito.
I think this one can be either deleted or replaced with something like an SBOM explanation.

[eskultety]

There is also another outdated document that was copied from Cachito. I think this one can be either deleted or replaced with something like an SBOM explanation.

Agreed, an SBOM section should be added to the main README file for now unless we have an extensive contents for this to be put in a standalone doc and this one should be dropped - I don't think we'll concern ourselves with content manifests other than what SBOM provides.

[slimreaper35]

So this is version 2.
I deleted metadata.md and refactored dependency_confusion.md except the package managers section.

[eskultety]

So this is version 2. I deleted metadata.md and refactored dependency_confusion.md except the package managers section.

so do you plan on extracting the package manager bits and moving them to the respective docs because right now it still looks confusing especially since you left the 'cachito' references in.

[eskultety]

So you left the package managers paragraphs in, but we still mention cachito here, that's confusing.

[slimreaper35]

I am still figuring out what to put there because I don't want to include general statements that should be part of the regular documentation. Anyway, I dropped those paragraphs so it is less confusing.

[eskultety]

Note you can't just remove content for your convenience if it doesn't fit the immediate intention like in this PR, because we'd lose legitimate content too (and we'd have to revert the change in the future). IOW part of dropping references to the original cachito code base is also finding new home to the information that still applies instead of just outright deleting it, leaving it for a potential future follow up, that's not how things should be done. IMO it's better to have more-or-less updated content with some inaccuracies which anyone willing to do so can identify and fix than no content at all and so I didn't go too deep into our code to verify every single sentence in those paragraphs, but as I outlined in my comments, much of the information is still valid and so I'd imagine these bits to be moved to the respective package manager docs to a section clearly denoting the dependency confusion matter.

[slimreaper35]

I turned it back to its original state. It's not a high priority now, so I'll leave it like that.

I still don't know what should be in the package manager section; my intention is to avoid general notes that are part of the regular documentation. So, later on, we don't have to adjust docs at multiple places.

[eskultety]

If you remove the whole dependency-related content from the respective package manager sections, what is the actual value of having these like you propose at all?

[eskultety]

So for pip, apart from index-url everything else should be more or less true even now for cachi2.

[eskultety]

I don't think we've made any distinctive changes to NPM after porting the code from cachito, so I guess it's still valid.

[eskultety]

This is not an adequate replacement because you just replaced Yarn v1 content (which we don't support yet) with a reference to our Yarn v2+ docs (indended, in reality you linked NPM instead).

[eskultety]

Note you can't just remove content for your convenience if it doesn't fit the immediate intention like in this PR, because we'd lose legitimate content too (and we'd have to revert the change in the future). IOW part of dropping references to the original cachito code base is also finding new home to the information that still applies instead of just outright deleting it, leaving it for a potential future follow up, that's not how things should be done. IMO it's better to have more-or-less updated content with some inaccuracies which anyone willing to do so can identify and fix than no content at all and so I didn't go too deep into our code to verify every single sentence in those paragraphs, but as I outlined in my comments, much of the information is still valid and so I'd imagine these bits to be moved to the respective package manager docs to a section clearly denoting the dependency confusion matter.