doc/md/guides: eval local flows

doc/md/guides/evaluation/01-intro.md

@@ -20,9 +20,9 @@ This guide is divided into the following sections:
 1. **Installation** - How to install Atlas and verify that it is able to understand your database.
 2. **Setting Up** - Setting up your project's structure for local work. 
 3. **Developer Workflow** - Review working with Atlas from the end-user perspective.
-4. **Setting Up CI Pipelines** - How to integrate Atlas into your CI/CD pipelines.
-5. **Security Checklist** - Things you should consider for when designing deployment pipelines.
-6. **Migrating  Existing Projects** - How to migrate existing projects to Atlas.
+4. **Migrating  Existing Projects** - How to migrate existing projects to Atlas.
+5. **Setting Up CI Pipelines** - How to integrate Atlas into your CI/CD pipelines.
+6. **Security Checklist** - Things you should consider for when designing deployment pipelines.
 
 ### Need help? 
 

doc/md/guides/evaluation/08-versioned-migrations-flows.mdx

@@ -1,4 +1,183 @@
 ---
-id: dev-flow-versioned
-title: Dev Flows for Versioned Migrations
----
+id: local-dev
+title: Local Development
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+With our setup complete, let's now turn to focusing on what it's like to work with Atlas in a local development environment.
+
+This section assumes that you have been following along with the previous sections and have already set
+up your project configuration file and schema.
+
+# Local Flows to Evaluate
+
+This section will guide you through the following local development flows:
+
+* Applying migrations locally
+
+* Planning migrations
+
+* Editing automatically generated migrations
+
+* Creating manual migrations
+
+* Undoing local changes
+
+## Applying migrations locally
+
+During development, developers often need to provision a local database with the latest schema.
+
+For the purpose of this guide we will assume that you have created a local database using docker and have stored
+the connection URL to it in an environment variable named `$LOCAL_DB_URL`.
+
+To apply the latest migrations to your local database, run the following command:
+
+```shell
+atlas migrate apply --env local --url "$LOCAL_DB_URL"
+```
+
+## Planning migrations
+
+As applications evolve, so do their database schemas. This section will guide you through the process of planning
+a new migration.
+
+#### Step 1: Modify the desired schema
+
+Atlas automatically plans migrations by comparing the desired schema with the _current_ schema of the database
+(as represented by replaying all existing migrations from start to end). To plan a new migration, you will need to
+modify the desired schema.
+
+For example, suppose you want to add a new column to a table, you would first modify your desired schema to include
+this column. Depending on how you defined your desired state in the [Schema-as-Code](/guides/evaluation/schema-as-code) step, here are some examples of
+how you might modify your schema:
+
+<Tabs
+  defaultValue="hcl"
+  groupId="languages"
+  values={[
+    { label: 'HCL', value: 'hcl' },
+    { label: 'SQL', value: 'sql' },
+    { label: 'ORM (Django, for example)', value: 'orm'}
+  ]
+}>
+<TabItem value="hcl">
+
+```diff title="schema.hcl"
+table "users" {
+   // redacted
++  column "email" {
++    type = text
++  }
+}
+```
+</TabItem>
+<TabItem value="sql">
+
+```diff title="schema.sql"
+CREATE TABLE users (
+  -- redacted
++ email TEXT
+);
+```
+
+</TabItem>
+<TabItem value="orm">
+
+```diff title="models.py"
+class User(models.Model):
+    # redacted
++   email = models.TextField()
+```
+
+</TabItem>
+</Tabs>
+
+#### Step 2: Plan the migration
+
+To plan the migration, run the following command:
+
+```shell
+atlas migrate diff --env local
+```
+
+This command will calculate the difference between the desired schema and the current schema of the database
+and output the migration that would be applied to bring the database schema up to date. For instance:
+
+```sql title="20240604131146_add_email_column.sql"
+ALTER TABLE users ADD COLUMN email TEXT;
+```
+
+#### Step 3: Verify the migration
+
+Atlas provides a `migrate lint` command that can be used to verify that the migration is valid and will not cause
+any issues when applied. To lint the migration, run the following command:
+
+```shell
+atlas migrate lint --env local --latest 1
+```
+
+This command will lint the latest migration in the `migrations/` directory. If you have multiple migrations, you can
+specify the number of migrations to lint by changing the `--latest` flag.
+
+## Editing Automatically Generated Migrations
+
+In some cases, you may need to edit a migration that was automatically generated by Atlas. For example, you may need
+want to set the transaction mode on a file level using a custom directive:
+
+```sql
+//highlight-next-line
+-- atlas:txmode none
+
+CREATE INDEX CONCURRENTLY name_idx ON users (name);
+```
+
+After manually editing a generated migration file, you must re-calculate the checksum of the migration directory
+using the `migrate hash` command:
+
+```shell
+atlas migrate hash --env local
+```
+
+## Created Manual Migrations
+
+In some cases, you may need to create a migration manually. One common example is when you need to backfill data
+in a table. To create a manual migration, run the following command:
+
+```shell
+atlas migrate new --env local my_new_migration
+```
+
+This command will create a new migration file in the `migrations/` directory with the name `<timestamp>_my_new_migration.sql`.
+
+Next, edit the contents of the generated migration file to include what you want and re-calculate the checksum of the
+migration directory using the `migrate hash` command:
+
+```shell
+atlas migrate hash --env local
+```
+
+As a convenience, you can use the `--edit` flag to open the newly created migration file in your default editor:
+
+```shell
+atlas migrate new --env local my_new_migration --edit
+```
+
+Upon saving the file, Atlas will automatically re-calculate the checksum of the migration directory for you.
+
+## Undoing Local Changes
+
+If you are not content with a migration you have planned and applied locally or if you want to revert a migration
+you have applied, *before deleting the latest migration file*, you can use the `migrate down` command:
+
+```shell
+atlas migrate down --env local --url "$LOCAL_DB_URL"
+```
+
+This will undo the statements in the latest migration file. If you would like to remove the migration file as well,
+you can use the `migrate rm` command:
+
+```shell
+atlas migrate rm --env local
+```

doc/website/sidebars.js

@@ -586,5 +586,16 @@ module.exports = {
                 }
             ]
         },
+        {
+            type: 'category',
+            label: 'Developer Flows',
+            collapsed: false,
+            items: [
+                {
+                    type: 'doc',
+                    id: 'guides/evaluation/local-dev'
+                }
+            ]
+        }
     ]
 };