docs: Define sorting in Style-guide.md [skip ci]

1 files changed, 32 insertions, 0 deletions

diff --git a/docs/markdown/Style-guide.md b/docs/markdown/Style-guide.md
index 900859261..30d30cf23 100644
--- a/docs/markdown/Style-guide.md
+++ b/docs/markdown/Style-guide.md
@@ -34,3 +34,35 @@ Try to keep cross compilation arguments away from your build files as
 much as possible. Keep them in the cross file instead. This adds
 portability, since all changes needed to compile to a different
 platform are isolated in one place.
+
+# Sorting source paths
+
+The source file arrays should all be sorted. This makes it easier to spot
+errors and often reduces merge conflicts. Furthermore, the paths should be
+sorted with a natural sorting algorithm, so that numbers are sorted in an
+intuitive way (`1, 2, 3, 10, 20` instead of `1, 10, 2, 20, 3`).
+
+Numbers should also be sorted before characters (`a111` before `ab0`).
+Furthermore, strings should be sorted case insensitive.
+
+Additionally, if a path contains a directory it should be sorted before
+normal files. This rule also applies recursively for subdirectories.
+
+The following example shows correct source list definition:
+
+```meson
+sources = files([
+  'aaa/a1.c',
+  'aaa/a2.c',
+  'bbb/subdir1/b1.c',
+  'bbb/subdir2/b2.c',
+  'bbb/subdir10/b3.c',
+  'bbb/subdir20/b4.c',
+  'bbb/b5.c',
+  'bbb/b6.c',
+  'f1.c',
+  'f2.c',
+  'f10.c,
+  'f20.c'
+])
+```