docs: Surface how team development works

[jemgillam]

From Discord https://discord.com/channels/489127045289476126/498852330754801666/1381598278738771968

how is team development supposed for graphile-migrate?
for example:

Developer 1 created in
migrations/current.sql
DROP VIEW IF EXISTS public.test_vew CASCADE
;
CREATE VIEW public.test_vew AS
SELECT 1
;

gm uncommit -> rebase -> gm commit => push
since order of migrations is important there isn't really a better solution

but if order is not important?

Order is almost always important, since it can have an impact on things like the order of columns in a table or the output of pg_dump. Graphile Migrate deliberately choses to support linear history only and this is enforced through hashing. As written in the docs (https://github.com/graphile/migrate?tab=readme-ov-file#collaboration) we recommend you only commit either just before or just after you merge to your main branch. Should you wish to try a different framework that does not hold the same opinions and allows for non-linear history, sqitch is commonly mentioned and seems to be well liked.

For each task we create a separate branch, the developer develops it, then this branch is tested, then it is merged into the master. When using graphile-migrate, you will have to run
gm uncommit -> rebase -> gm commit => push before merging into the master

You don't need to do that, you can just run graphile-migrate watch --once rather than committing. You should almost never have to uncommit. You can test your PR without committing the migration.

I've never considered this before... but we could probably integrate it into a git merge hook

i have a check that blocks merging if something hasn't been committed to avoid accidents

If I felt the need to automate it, I'd probably just add a GitHub Action on main that commits pending migration and pushes it.

you'd still run the risk of merging in the wrong order breaking main

True, it would introduce a race condition.