Merge pull request #36 from ko4life-net/submodule-archive

Externalize migration scripts archive dir into a submodule ko-db-archive

.gitattributes

@@ -1,4 +1,5 @@
 * text=auto
+*.md text eol=lf
 *.sql linguist-detectable=true
 *.sql linguist-language=tsql
 *.sql diff

.gitmodules

@@ -0,0 +1,5 @@
+[submodule "src/migration/archive"]
+	path = src/migration/archive
+	url = ../ko-db-archive
+	shallow = true
+	depth = 1

src/migration/README.md

@@ -1,26 +1,43 @@
-# Migration scripts
-
-Add here scripts that alters the existing database's schema, procedures, data and misc changes.
-
-Couple of rules and notes when writing migration scripts:
-- Always assume the database containing data, even if you just modify an empty table
-- When altering the schema, adding comments (`--` for tsql) are encouraged
-- When submitting a PR, please generate a `*.diff` file and commit it (`.\import.ps1 -generate_diffs`)
-- Every migration script should start with max 4 leading zeros (example `0001_insert_user.sql`)
-
-## Creating a new release
-
-Below are instructions for the release engineer in order to create a new db release:
-- Create a new release branch following the db new release version according version semantics (`git checkout -b release/1.0.1`)
-- Run the import script skipping the migration scripts (`.\import.ps1 -skip_migration_scripts`)
-- Run the export script, to be sure that no diff is produced (`.\export.ps1` and then `git status`)
-  - If there are local changes, something is probably off. Repeat the steps above
-  - If you're sure all in order, best is if you create a new separate PR with the changes, in case empty spaces and such were added
-- Run the import script again with the migration scripts and produce diffs (`.\import.ps1 -generate_diffs`)
-- Move all migration scripts and its `*.diff` files to the `archived` directory
-- Lastly run the export script once more, but this time you'll have the actual changes from the migration scripts affecting the actual schema
-- Git commit all the changes (`Bump version from 1.0.0 to 1.0.1.`)
-  - Check the final diff that all looks in order
-- Create a PR and merge after approval
-- After merging, create a new release using GitHub web interface and add description to the release highlighting the important changes
-  - Note that it will create a new tag automatically that we can reference later from other repositories
+# Migration Scripts
+
+This directory contains sql scripts for updating the database schema, procedures, data, and other changes.
+
+## Guidelines for Writing Migration Scripts
+
+- Add comments (`--` for T-SQL) to explain schema changes.
+- When submitting a PR, generate and commit a `*.diff` file using `.\import.ps1 -generate_diffs`.
+- Name migration scripts with up to four leading zeros (e.g., `0001_insert_user.sql`).
+
+## Creating a New Release
+
+- **Create a release branch**
+  - Use semantic versioning for the branch name (e.g., `release/1.0.1`).
+
+- **Run the import script (skip migration scripts)**
+  - Execute: `.\import.ps1 -skip_migration_scripts`.
+
+- **Run the export script to validate**
+  - Execute: `.\export.ps1`.
+  - Use `git status` to check for changes.
+    - If changes exist, investigate or address them in a separate PR if valid (e.g., whitespace).
+
+- **Run the import script with migration scripts**
+  - Execute: `.\import.ps1 -generate_diffs`.
+
+- **Archive processed migration scripts**
+  - Move processed migration scripts and their `*.diff` files to the `archive` submodule.
+  - Commit and push changes. Update `ko-db` to reference the new commit.
+
+- **Final export and validation**
+  - Execute the export script again to capture changes from migration scripts.
+
+- **Commit changes**
+  - Use a descriptive message (e.g., `Bump version from 1.0.0 to 1.0.1`).
+  - Review the final diff for correctness.
+
+- **Create and merge a pull request**
+  - Open a PR, get approval, and merge it into the main branch.
+
+- **Create a release on GitHub**
+  - Use the GitHub interface to create a release, describing key changes.
+  - A new tag will be generated automatically.