Document opinion: order of migration matters, hence linear

[benjie]

Imagine you have the table create table my_table (id serial primary key); and these two migrations on separate branches:

alter table my_table add column column_1 int;

alter table my_table add column column_a text;

At first you might think these don't conflict, but actually they do, the end result is dependent on order:

create table my_table (
  id serial primary key,
  column_1 int,
  column_a text
);

versus:

create table my_table (
  id serial primary key,
  column_a text,
  column_1 int
);

Now if you try and represent this table value as a tuple - (1, 2, 'three')::my_table - then this will work against one DB but fail against the other. Order of columns is significant.

So it's best to ensure that your migrations are completely linear.