containerbuildsystem / cachi2

Cachi2 is a CLI tool that pre-fetches your project's dependencies to aid in making your build process network-isolated.

GNU General Public License v3.0

8 stars 26 forks source link

docs cleanup #569

Open slimreaper35 opened 3 months ago

slimreaper35 commented 3 months ago

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)

slimreaper35 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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

eskultety commented 3 months ago

So this is version 2. I deleted metadata.md and refactored _dependencyconfusion.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.