Object file doc - #8433
Object file doc#8433
Conversation
github-actions
Bot
added
the
type/documentation
WalkthroughThis pull request introduces new documentation for Infrahub's file object feature and reorganizes related documentation navigation. A new file 🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Tip Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
docs/docs/topics/file-object.mdx (1)
13-13: Minor passive voice: "is maintained manually."Rewrite to active voice per documentation guidelines.
✏️ Proposed fix
-When a circuit contract expires, the team managing the circuit may not know where to find the document. When a firmware image needs to be traced back to a specific device deployment, the link between the two is maintained manually, if at all. +When a circuit contract expires, the team managing the circuit may not know where to find the document. When a firmware image needs to be traced back to a specific device deployment, teams maintain the link manually, if at all.As per coding guidelines: "Use active voice in documentation (e.g., 'Create a branch' not 'A branch can be created')."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/docs/topics/file-object.mdx` at line 13, Replace the passive clause "is maintained manually" with an active-voice phrasing in that paragraph so it reads from the actor's perspective; for example, change "the link between the two is maintained manually, if at all" to "teams maintain the link manually, if at all" (locate the sentence containing "is maintained manually" in the file and update it).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/docs/topics/file-object.mdx`:
- Line 135: Update the sentence in the Artifact description so the
Infrahub-specific feature name is capitalized: change the lowercase
"transformations" to "Transformations" in the line
"**[Artifact](./artifact.mdx)**: While artifacts are system-generated outputs
from transformations, file objects are user-uploaded documents." to conform to
the guideline of capitalizing Infrahub-specific terms (e.g., Transformation(s)).
- Around line 78-80: The text incorrectly calls the storage a
"content-addressable store" while elsewhere saying files are identified by
UUIDs; change the wording to "immutable object store" or "append-only object
store" and update the paragraph around the `storage_id` description to remove
any CAS implications (no content-hash deduplication), e.g., state that each file
version is stored under a new UUID and that the store is immutable so prior
versions remain accessible via the graph node's `storage_id`; ensure references
to deduplication or content-derived keys are removed or clarified.
In `@docs/sidebars.ts`:
- Line 188: Update the sidebar label string that currently reads 'Transforms &
Artifacts' to use the noun form per guidelines: change it to 'Transformations &
Artifacts' wherever the label identifier 'Transforms & Artifacts' appears (e.g.,
in the sidebar item label property) so the UI text conforms to the
"Transformation(s)" rule.
---
Nitpick comments:
In `@docs/docs/topics/file-object.mdx`:
- Line 13: Replace the passive clause "is maintained manually" with an
active-voice phrasing in that paragraph so it reads from the actor's
perspective; for example, change "the link between the two is maintained
manually, if at all" to "teams maintain the link manually, if at all" (locate
the sentence containing "is maintained manually" in the file and update it).
| Files are stored in a content-addressable store that is completely separate from the graph database. The storage layer is a key-value system where each file is identified by a UUID. Once a file is stored, it is never modified or deleted. This immutability is what enables version control and time travel for files. | ||
|
|
||
| The graph database handles all the branch-aware, time-aware logic. A file object node contains a `storage_id` attribute that points to the stored file. When you update a file, Infrahub stores the new version under a new UUID and updates the node's `storage_id` on the current branch. The original file remains untouched in storage, and any branch or point in time that referenced the old `storage_id` continues to resolve to the original file. |
There was a problem hiding this comment.
"Content-addressable" contradicts "identified by a UUID" — inaccurate terminology.
A content-addressable store (CAS) derives the storage key from the file's content hash, enabling deduplication (the same bytes always map to the same key). The document simultaneously calls the store "content-addressable" (Line 78) and says files are "identified by a UUID" (Line 79), which are mutually exclusive: UUIDs are assigned randomly, not derived from content. Line 80 confirms UUID semantics: "Infrahub stores the new version under a new UUID." Replace "content-addressable store" with a more accurate term such as "immutable object store" or "append-only object store."
✏️ Proposed fix
-Files are stored in a content-addressable store that is completely separate from the graph database.
+Files are stored in an immutable object store that is completely separate from the graph database.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Files are stored in a content-addressable store that is completely separate from the graph database. The storage layer is a key-value system where each file is identified by a UUID. Once a file is stored, it is never modified or deleted. This immutability is what enables version control and time travel for files. | |
| The graph database handles all the branch-aware, time-aware logic. A file object node contains a `storage_id` attribute that points to the stored file. When you update a file, Infrahub stores the new version under a new UUID and updates the node's `storage_id` on the current branch. The original file remains untouched in storage, and any branch or point in time that referenced the old `storage_id` continues to resolve to the original file. | |
| Files are stored in an immutable object store that is completely separate from the graph database. The storage layer is a key-value system where each file is identified by a UUID. Once a file is stored, it is never modified or deleted. This immutability is what enables version control and time travel for files. | |
| The graph database handles all the branch-aware, time-aware logic. A file object node contains a `storage_id` attribute that points to the stored file. When you update a file, Infrahub stores the new version under a new UUID and updates the node's `storage_id` on the current branch. The original file remains untouched in storage, and any branch or point in time that referenced the old `storage_id` continues to resolve to the original file. |
🧰 Tools
🪛 LanguageTool
[style] ~80-~80: This phrase is redundant. Consider writing “point” or “time”.
Context: ...untouched in storage, and any branch or point in time that referenced the old storage_id co...
(MOMENT_IN_TIME)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs/topics/file-object.mdx` around lines 78 - 80, The text incorrectly
calls the storage a "content-addressable store" while elsewhere saying files are
identified by UUIDs; change the wording to "immutable object store" or
"append-only object store" and update the paragraph around the `storage_id`
description to remove any CAS implications (no content-hash deduplication),
e.g., state that each file version is stored under a new UUID and that the store
is immutable so prior versions remain accessible via the graph node's
`storage_id`; ensure references to deduplication or content-derived keys are
removed or clarified.
| - **[Proposed changes](./proposed-change.mdx)**: File updates go through the same review process as data changes. | ||
| - **[Object storage](./object-storage.mdx)**: File content is persisted in Infrahub's storage layer, which supports local and S3 backends. | ||
| - **[Permissions and roles](./permissions-roles.mdx)**: File access is controlled by the same role-based permissions as other data. | ||
| - **[Artifact](./artifact.mdx)**: While artifacts are system-generated outputs from transformations, file objects are user-uploaded documents. Both use the object storage layer, but they serve different purposes. |
There was a problem hiding this comment.
Capitalize "Transformations" as an Infrahub-specific term.
"from transformations" refers to the Infrahub Transformations feature and must be capitalized.
✏️ Proposed fix
-- **[Artifact](./artifact.mdx)**: While artifacts are system-generated outputs from transformations, file objects are user-uploaded documents.
+- **[Artifact](./artifact.mdx)**: While artifacts are system-generated outputs from Transformations, file objects are user-uploaded documents.As per coding guidelines: "Capitalize Infrahub-specific terms: Generator(s), Transformation(s), Profile(s), Resource Manager."
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **[Artifact](./artifact.mdx)**: While artifacts are system-generated outputs from transformations, file objects are user-uploaded documents. Both use the object storage layer, but they serve different purposes. | |
| - **[Artifact](./artifact.mdx)**: While artifacts are system-generated outputs from Transformations, file objects are user-uploaded documents. Both use the object storage layer, but they serve different purposes. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docs/topics/file-object.mdx` at line 135, Update the sentence in the
Artifact description so the Infrahub-specific feature name is capitalized:
change the lowercase "transformations" to "Transformations" in the line
"**[Artifact](./artifact.mdx)**: While artifacts are system-generated outputs
from transformations, file objects are user-uploaded documents." to conform to
the guideline of capitalizing Infrahub-specific terms (e.g., Transformation(s)).
| { | ||
| type: 'category', | ||
| label: 'Transforms', | ||
| label: 'Transforms & Artifacts', |
There was a problem hiding this comment.
Use "Transformations" not "Transforms" — noun form required by guidelines.
'Transforms & Artifacts' uses "Transforms" as a noun. As per coding guidelines, the label should read 'Transformations & Artifacts'.
✏️ Proposed fix
- label: 'Transforms & Artifacts',
+ label: 'Transformations & Artifacts',As per coding guidelines: "Never use 'transform' or 'transforms' as a noun; always use 'Transformation' or 'Transformations'."
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| label: 'Transforms & Artifacts', | |
| label: 'Transformations & Artifacts', |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/sidebars.ts` at line 188, Update the sidebar label string that currently
reads 'Transforms & Artifacts' to use the noun form per guidelines: change it to
'Transformations & Artifacts' wherever the label identifier 'Transforms &
Artifacts' appears (e.g., in the sidebar item label property) so the UI text
conforms to the "Transformation(s)" rule.
2 participants
Summary by CodeRabbit