Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Add images and more details to the topics - proposed change documentation. #5593

Open
wants to merge 3 commits into
base: stable
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .vale/styles/spelling-exceptions.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ agent
Alibaba
Ansible
append_git_suffix
approvers
APIs
artifact_definitions
artifact_name
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
62 changes: 62 additions & 0 deletions docs/docs/topics/proposed-change.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
---
title: Proposed change
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Proposed change

Expand All @@ -10,6 +12,8 @@ A proposed change provides a way to review and discuss how two branches differ f

A reviewer of the proposed change can open discussions, write comments, and request changes. Once you resolve any requested change, the reviewer would approve the proposed change before they merge it.

![](../media/topics/proposed_change/pc_comments_1.png)

## An alternative approach to diff

In a pull request on GitHub, the diff between two branches is seen from a plain text point of view. A proposed change in Infrahub allows you to see changes in data, as well as the type of diff you’d see in Git. By combining the two, someone reviewing a proposed change in Infrahub can view the diff between [artifacts](artifact) on each branch.
Expand All @@ -22,6 +26,64 @@ Just like you’d expect for a GitHub pull request, you can run checks on a prop

Infrahub handles custom checks with code through Git repositories. These Checks let you verify the integrity of the database using your custom business logic. A check of this type could be anything you can imagine. An example could be to ensure that at least one router on each site is in an operational status as opposed to being in maintenance mode.

<Tabs>
<TabItem value="Overview" default>
The overview tab provides the landing page for the Proposed Change. This tab allows you to do the following:
- Approve, Merge, or close the Proposed Change
- View the state, source and target branches, created by, approvers, and reviewers
![](../media/topics/proposed_change/pc_tab_overview.png)
</TabItem>
<TabItem value="Data" default>
The data tab provides the diff functionality to allow users to see the changes that are being proposed in the change.
![](../media/topics/proposed_change/pc_tab_data.png)
</TabItem>
<TabItem value="Files" default>
The files tab provides insight into any files within the Git repository that has been changed.
</TabItem>
<TabItem value="Artifacts" default>
The artifacts tab provides a diff view of artifacts that were generated as part of the Proposed Change.
![](../media/topics/proposed_change/pc_tab_artifacts.png)
</TabItem>
<TabItem value="Schema" default>
The schemas tab provides insight into any schema changes that were made within the branch.
![](../media/topics/proposed_change/pc_tab_schema.png)
</TabItem>
<TabItem value="Checks" default>
The checks tab provides an details about the CI Integration checks that are ran in each Proposed Change. There are several checks that **can** be ran depending on the changes in the branch or repository.
- **Artifact**: If data is changed or a template file that affects an artifact, new artifacts will be generated.
- **Data**: The data integrity checks run on every Proposed Change to ensure there are no data integrity issues such as conflicts.
- **Generator**: Provides details about generators that are ran in the Proposed Change, if any data is changed that affects a generator.
- **Schema**: The schema check will provide insight into any issues if schema was changed within a branch.
- **User**: These are user defined checks that are executed and ensure that any changes adhere to custom business logic.
![](../media/topics/proposed_change/pc_tab_checks.png)
</TabItem>
<TabItem value="Tasks" default>
The tasks tab provides details of any tasks that have been executed for the proposed change.
![](../media/topics/proposed_change/pc_tab_tasks.png)
</TabItem>
</Tabs>

## Conflict resolution

Infrahub will prevent merging a proposed change if there is a data conflict between the branches. An example of such a conflict could be if someone were to update the same attribute of an object in both branches. In order to merge a proposed change that has conflicts, they need to be resolved. To resolve conflicts, you need to review data integrity checks and choose which branch to keep in the change checks section.

### Conflict checks

Infrahub will determine if there are conflicts between the changed data and provide two ways to view conflicts.

<Tabs>
<TabItem value="Data Tab" default>
![](../media/topics/proposed_change/pc_data_conflict.png)
</TabItem>
<TabItem value="Checks Tab" default>
![](../media/topics/proposed_change/pc_check_conflict.png)
</TabItem>
</Tabs>

### Resolving conflicts

To resolve conflicts, navigate to the Proposed Change's **Data** tab and find the conflict by selecting the conflict icon.

Once the conflict(s) are shown, you can select which branch's data to resolve the conflict.

![](../media/topics/proposed_change/pc_conflict_fix.png)
Loading