make it a sep page

src/data/sidebar.ts

@@ -35,6 +35,7 @@ export const sidebarContent: ISidebarContent = [
         subTitle: makePage("Foundations", "guides"),
         pages: [
           makePage("Projects", "guides"),
+          makePage("Staged Changes", "guides"),
           makePage("Services", "guides"),
           makePage("Variables", "guides"),
           makePage("Volumes", "guides"),

src/docs/guides/environments.md

@@ -11,51 +11,26 @@ Railway supports complex development workflows through environments, giving you
     - **Duplicate Environment** creates a copy of the selected environment, including services, variables, and configuration.  
 
         When the duplicate environment is created, all services and their configuration will be staged for deployment.
-        *You must review and approve the [staged changes](#staged-changes) before the services deploy.*
+        *You must review and approve the [staged changes](/guides/staged-changes) before the services deploy.*
 
     - **Empty Environment** creates an empty environment with no services.
 
-## Staged Changes
-
-When you make a change to a service or volume, that change will be staged.
-
-1. The number of staged changes will be displayed in a banner in the top left corner of the canvas
-2. Staged changes will appear as purple in the UI
-3. Each service card that has received a change will be tagged "Edited"
-
-<Image src="https://res.cloudinary.com/railway/image/upload/v1702077687/docs/staged-changes/wl1qxxj8mpbej70i042r.png"
-            alt="Staged changes on Railway canvas"
-            layout="responsive"
-            width={1423} height={826} quality={100} />
-
-### Review and Deploy Changes
-
-To review the staged changes, click the "Details" button in the banner.  Here, you will see a diff of old and new values.  You can discard a change by clicking the "x" to the right of the change.
-
-You can optionally add a commit message that will appear in the [activity feed](/guides/projects#viewing-recent-activity).
-
-<Image src="https://res.cloudinary.com/railway/image/upload/v1702078631/docs/staged-changes/a9xic5xjerg0t6ksogzh.png"
-            alt="Staged changes on Railway canvas"
-            layout="responsive"
-            width={1108} height={841} quality={100} />
-
-Clicking "Deploy" will deploy all of the changes at once. Any services that are affected will be redeployed.
-
 ## Sync Environments
 
 You can easily sync environments to _import_ one or more services from one environment into another environment.
 
 1. Ensure your current environment is the one that should *receive* the synced service(s)
 2. Click `Sync` at the top of the canvas
 3. Select the environment from which to sync changes
-4. Review the staged changes to keep or discard the desired services and configuration
+4. Upon sync, each service card that has received a change will be tagged "New", "Edited", "Removed"
+4. Review the [staged changes](/guides/staged-changes) by clicking Details on the staged changes banner
 5. Click "Deploy" once you are ready to apply the changes and re-deploy
 
 ### Caveats
 
 - Networking changes are not yet staged and are applied immediately.
 - Adding databases or templates will only affect the current environment. However, they do not yet create a commit in the history.
-- When staged changes are enabled, forking environments is disabled. Staging changes is our long-term vision for environments which will incorporate the best parts of forking environments. However, at the moment the two features are incompatible.
+
 
 ## Enable PR Environments
 
@@ -75,6 +50,6 @@ Railway will not deploy a PR branch from a user who is not in your team or invit
 
 ## Forked Environments
 
-As of January 2024, Forked environments have been deprecated in favor of Isolated Environments with the ability to Sync.
+As of January 2024, forked environments have been deprecated in favor of Isolated Environments with the ability to Sync.
 
-If you still have a forked environment, it will remain in your project until you merge it.
+Any environments forked prior to this change will remain, however, you must adopt the [Sync Environments](#sync-environments) flow, in order to merge changes into your base environment.

src/docs/guides/services.md

@@ -4,6 +4,8 @@ title: Managing Services
 
 A Railway Service is a deployment target for your application.
 
+*As you create and manage your services, your changes will be collected in a set of [staged changes](/guides/staged-changes) that you must review and deploy, in order to apply them.*
+
 ## Creating A Service
 
 Create a service by clicking the `New` button in the top right corner of your project canvas, or by typing new service from the **command palette**, accessible via `CMD + K` (Mac) or `Ctrl + K`(Windows).

src/docs/guides/staged-changes.md

@@ -0,0 +1,32 @@
+---
+title: Staged Changes
+---
+
+Changes made in your Railway project, like adding, removing, or making changes to components, will be staged in a changeset for you to review and apply.
+
+It is important to be familiar with this flow as you explore the upcoming guides.
+
+### What to Expect
+
+As you create or update components within your project -
+
+1. The number of staged changes will be displayed in a banner in the top left corner of the canvas
+2. Staged changes will appear as purple in the UI
+
+<Image src="https://res.cloudinary.com/railway/image/upload/v1702077687/docs/staged-changes/wl1qxxj8mpbej70i042r.png"
+            alt="Staged changes on Railway canvas"
+            layout="responsive"
+            width={1423} height={826} quality={100} />
+
+### Review and Deploy Changes
+
+To review the staged changes, click the "Details" button in the banner.  Here, you will see a diff of old and new values.  You can discard a change by clicking the "x" to the right of the change.
+
+You can optionally add a commit message that will appear in the [activity feed](/guides/projects#viewing-recent-activity).
+
+<Image src="https://res.cloudinary.com/railway/image/upload/v1702078631/docs/staged-changes/a9xic5xjerg0t6ksogzh.png"
+            alt="Staged changes on Railway canvas"
+            layout="responsive"
+            width={1108} height={841} quality={100} />
+
+Clicking "Deploy" will deploy all of the changes at once. Any services that are affected will be redeployed.

src/docs/guides/variables.md

@@ -13,6 +13,8 @@ When defined, they are made available to your application as environment variabl
 
 In Railway, there is also a notion of configuration variables which allow you to control the behavior of the platform.
 
+*Adding, updating, or removing variables, results in a set of [staged changes](/guides/staged-changes) that you must review and deploy, in order to apply them.*
+
 ## Service variables
 
 Variables scoped to individual services can be defined by navigating to a service's "Variables" tab.