Add comments

pageserver/src/tenant/timeline.rs

@@ -3828,8 +3828,12 @@ impl Timeline {
                     "keeping {} because it is the latest layer",
                     l.filename().file_name()
                 );
-                // collect delta key ranges that need image layers to allow garbage
-                // collecting the layers
+                // Collect delta key ranges that need image layers to allow garbage
+                // collecting the layers.
+                // It is not so obvious whether we need to propagate information only about
+                // delta layers. Image layers can form "stairs" preventing old image from been deleted.
+                // But image layers are in any case less sparse than delta layers. Also we need some
+                // protection from replacing recent image layers with new one after each GC iteration.
                 if l.is_incremental() {
                     let mut to_remove: Vec<Key> = Vec::new();
                     let mut insert_new_range = true;

test_runner/regress/test_gc_old_layers.py

@@ -2,7 +2,13 @@ import pytest
 from fixtures.log_helper import log
 from fixtures.neon_fixtures import NeonEnvBuilder
 
-
+#
+# Test that GC is able to collect all old layers even if them are forming
+# "stairs" and there are not three delta layers since last image layer.
+# Information about image layers needed to collect old layers should
+# be propagated by GC to compaction task which should take in in account
+# when make a decision which new image layers needs to be created
+#
 @pytest.mark.timeout(10000)
 def test_gc_old_layers(neon_env_builder: NeonEnvBuilder):
     env = neon_env_builder.init_start()