diff --git a/.vale/styles/spelling-exceptions.txt b/.vale/styles/spelling-exceptions.txt
index d018438b7b..dbdc55957c 100644
--- a/.vale/styles/spelling-exceptions.txt
+++ b/.vale/styles/spelling-exceptions.txt
@@ -2,6 +2,7 @@ agent
Alibaba
Ansible
append_git_suffix
+approvers
APIs
artifact_definitions
artifact_name
diff --git a/docs/docs/media/topics/proposed_change/pc_check_conflict.png b/docs/docs/media/topics/proposed_change/pc_check_conflict.png
new file mode 100644
index 0000000000..5c88cc86b6
Binary files /dev/null and b/docs/docs/media/topics/proposed_change/pc_check_conflict.png differ
diff --git a/docs/docs/media/topics/proposed_change/pc_comments_1.png b/docs/docs/media/topics/proposed_change/pc_comments_1.png
new file mode 100644
index 0000000000..fa57472b55
Binary files /dev/null and b/docs/docs/media/topics/proposed_change/pc_comments_1.png differ
diff --git a/docs/docs/media/topics/proposed_change/pc_conflict_fix.png b/docs/docs/media/topics/proposed_change/pc_conflict_fix.png
new file mode 100644
index 0000000000..edb38ac287
Binary files /dev/null and b/docs/docs/media/topics/proposed_change/pc_conflict_fix.png differ
diff --git a/docs/docs/media/topics/proposed_change/pc_data_conflict.png b/docs/docs/media/topics/proposed_change/pc_data_conflict.png
new file mode 100644
index 0000000000..2730700206
Binary files /dev/null and b/docs/docs/media/topics/proposed_change/pc_data_conflict.png differ
diff --git a/docs/docs/media/topics/proposed_change/pc_diff_icons.png b/docs/docs/media/topics/proposed_change/pc_diff_icons.png
new file mode 100644
index 0000000000..efb1f3614c
Binary files /dev/null and b/docs/docs/media/topics/proposed_change/pc_diff_icons.png differ
diff --git a/docs/docs/media/topics/proposed_change/pc_tab_artifacts.png b/docs/docs/media/topics/proposed_change/pc_tab_artifacts.png
new file mode 100644
index 0000000000..a4224b4b23
Binary files /dev/null and b/docs/docs/media/topics/proposed_change/pc_tab_artifacts.png differ
diff --git a/docs/docs/media/topics/proposed_change/pc_tab_checks.png b/docs/docs/media/topics/proposed_change/pc_tab_checks.png
new file mode 100644
index 0000000000..cdbae38e92
Binary files /dev/null and b/docs/docs/media/topics/proposed_change/pc_tab_checks.png differ
diff --git a/docs/docs/media/topics/proposed_change/pc_tab_data.png b/docs/docs/media/topics/proposed_change/pc_tab_data.png
new file mode 100644
index 0000000000..7b00441470
Binary files /dev/null and b/docs/docs/media/topics/proposed_change/pc_tab_data.png differ
diff --git a/docs/docs/media/topics/proposed_change/pc_tab_overview.png b/docs/docs/media/topics/proposed_change/pc_tab_overview.png
new file mode 100644
index 0000000000..41b3aea2db
Binary files /dev/null and b/docs/docs/media/topics/proposed_change/pc_tab_overview.png differ
diff --git a/docs/docs/media/topics/proposed_change/pc_tab_schema.png b/docs/docs/media/topics/proposed_change/pc_tab_schema.png
new file mode 100644
index 0000000000..f272cbd6dc
Binary files /dev/null and b/docs/docs/media/topics/proposed_change/pc_tab_schema.png differ
diff --git a/docs/docs/media/topics/proposed_change/pc_tab_tasks.png b/docs/docs/media/topics/proposed_change/pc_tab_tasks.png
new file mode 100644
index 0000000000..282009ddcc
Binary files /dev/null and b/docs/docs/media/topics/proposed_change/pc_tab_tasks.png differ
diff --git a/docs/docs/topics/proposed-change.mdx b/docs/docs/topics/proposed-change.mdx
index 2de2db4080..d382b3fbac 100644
--- a/docs/docs/topics/proposed-change.mdx
+++ b/docs/docs/topics/proposed-change.mdx
@@ -1,6 +1,8 @@
---
title: Proposed change
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
# Proposed change
@@ -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.
+
+
## 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.
@@ -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.
+
+
+ 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
+ 
+
+
+ The data tab provides the diff functionality to allow users to see the changes that are being proposed in the change.
+ 
+
+
+ The files tab provides insight into any files within the Git repository that has been changed.
+
+
+ The artifacts tab provides a diff view of artifacts that were generated as part of the Proposed Change.
+ 
+
+
+ The schemas tab provides insight into any schema changes that were made within the branch.
+ 
+
+
+ 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.
+ 
+
+
+ The tasks tab provides details of any tasks that have been executed for the proposed change.
+ 
+
+
+
## 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.
+
+
+
+ 
+
+
+ 
+
+
+
+### 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.
+
+