From 17ce9bc0e536067cfa1a05cb057014e3b1c2c449 Mon Sep 17 00:00:00 2001
From: Daniel Mensinger <daniel@mensinger-ka.de>
Date: Mon, 4 Mar 2019 16:49:02 +0100
Subject: docs: Define sorting in Style-guide.md [skip ci]

---
 docs/markdown/Style-guide.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

(limited to 'docs/markdown')

diff --git a/docs/markdown/Style-guide.md b/docs/markdown/Style-guide.md
index 9008592..30d30cf 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'
+])
+```
-- 
cgit v1.1