{"thread":{"id":"59283","subject":"[RFC PATCH v1] test-lib: move comment about test_description","startedAt":"2023-02-21T23:22:54Z","lastAt":"2023-02-26T10:53:11Z","messageCount":4,"participants":["Andrei Rybak","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"472418","messageId":"20230221232245.155960-1-rybak.a.v@gmail.com","threadId":"59283","inReplyTo":null,"subject":"[RFC PATCH v1] test-lib: move comment about test_description","fromName":"Andrei Rybak","fromEmail":"rybak.a.v@gmail.com","sentAt":"2023-02-21T23:22:45Z","receivedAt":"2023-02-21T23:22:54Z","isPatch":true,"sender":{"key":"rybak.a.v@gmail.com","avatar":"https://avatars.githubusercontent.com/u/624072?v=4"},"body":"When a comment describing how each test file should start was added in\ncommit [1], it was the second comment of t/test-lib.sh.  The comment\ndescribes how variable \"test_description\" is supposed to be assigned at\nthe top of each test file.  However, even in [1], the comment was ten\nlines away from the usage of the variable by test-lib.sh.  Since then,\nthe comment has drifted away both from the top of the file and from the\nusage of the variable.  The comment just sits in the middle of the\ninitialization of the test library, surrounded by unrelated code.\n\nMove the comment describing how variable \"test_description\" is supposed\nto be assigned to just above the usage of the variable in test-lib.sh.\n\nAn alternative is to just drop this comment, since assignment of\n\"test_description\" and the process of writing tests in general are\ndescribed in detail in \"t/README\".\n\n[1] e1970ce43a (\"[PATCH 1/2] Test framework take two.\", 2005-05-13)\n\nSigned-off-by: Andrei Rybak <rybak.a.v@gmail.com>\n---\n t/test-lib.sh | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/t/test-lib.sh b/t/test-lib.sh\nindex d272cca008..c21934251d 100644\n--- a/t/test-lib.sh\n+++ b/t/test-lib.sh\n@@ -645,12 +645,6 @@ u200c=$(printf '\\342\\200\\214')\n \n export _x05 _x35 LF u200c EMPTY_TREE EMPTY_BLOB ZERO_OID OID_REGEX\n \n-# Each test should start with something like this, after copyright notices:\n-#\n-# test_description='Description of this test...\n-# This test checks if command xyzzy does the right thing...\n-# '\n-# . ./test-lib.sh\n test \"x$TERM\" != \"xdumb\" && (\n \t\ttest -t 1 &&\n \t\ttput bold >/dev/null 2>&1 &&\n@@ -746,6 +740,12 @@ then\n \tfi\n fi\n \n+# Each test should start with something like this, after copyright notices:\n+#\n+# test_description='Description of this test...\n+# This test checks if command xyzzy does the right thing...\n+# '\n+# . ./test-lib.sh\n test \"${test_description}\" != \"\" ||\n error \"Test script did not set test_description.\"\n \n-- \n2.39.2\n\n"},{"id":"472730","messageId":"20230225190526.21780-1-rybak.a.v@gmail.com","threadId":"59283","inReplyTo":"20230221232245.155960-1-rybak.a.v@gmail.com","subject":"[RFC PATCH v2] test-lib: drop comment about test_description","fromName":"Andrei Rybak","fromEmail":"rybak.a.v@gmail.com","sentAt":"2023-02-25T19:05:26Z","receivedAt":"2023-02-25T19:05:33Z","isPatch":true,"sender":{"key":"rybak.a.v@gmail.com","avatar":"https://avatars.githubusercontent.com/u/624072?v=4"},"body":"When a comment describing how each test file should start was added in\ncommit [1], it was the second comment of t/test-lib.sh.  The comment\ndescribes how variable \"test_description\" is supposed to be assigned at\nthe top of each test file.  However, even in [1], the comment was ten\nlines away from the usage of the variable by test-lib.sh.  Since then,\nthe comment has drifted away both from the top of the file and from the\nusage of the variable.  The comment just sits in the middle of the\ninitialization of the test library, surrounded by unrelated code, almost\none hundred lines away from the usage of \"test_description\".\n\nNobody has noticed this drift during evolution of test-lib.sh, which\nsuggests that this comment has outlived its usefulness.  The assignment\nof \"test_description\" and the process of writing tests in general are\ndescribed in detail in \"t/README\".  So drop the obsolete comment.\n\nAn alternative solution is to move the comment down to the usage of\nvariable \"test_description\".\n\n[1] e1970ce43a (\"[PATCH 1/2] Test framework take two.\", 2005-05-13)\n\nSigned-off-by: Andrei Rybak <rybak.a.v@gmail.com>\n---\n\n\n  On 2023-02-22T00:22, Andrei Rybak wrote:\n  > Move the comment describing how variable \"test_description\" is supposed\n  > to be assigned to just above the usage of the variable in test-lib.sh.\n  > \n  > An alternative is to just drop this comment, since assignment of\n  > \"test_description\" and the process of writing tests in general are\n  > described in detail in \"t/README\".\n\nHere's the alternative solution described in the commit message of v1.\nI put the RFC tag in the subject, because I'm not sure which of the two\napproaches -- move in v1 or drop in v2 -- is better.\n\n t/test-lib.sh | 6 ------\n 1 file changed, 6 deletions(-)\n\ndiff --git a/t/test-lib.sh b/t/test-lib.sh\nindex d272cca008..62136caee5 100644\n--- a/t/test-lib.sh\n+++ b/t/test-lib.sh\n@@ -645,12 +645,6 @@ u200c=$(printf '\\342\\200\\214')\n \n export _x05 _x35 LF u200c EMPTY_TREE EMPTY_BLOB ZERO_OID OID_REGEX\n \n-# Each test should start with something like this, after copyright notices:\n-#\n-# test_description='Description of this test...\n-# This test checks if command xyzzy does the right thing...\n-# '\n-# . ./test-lib.sh\n test \"x$TERM\" != \"xdumb\" && (\n \t\ttest -t 1 &&\n \t\ttput bold >/dev/null 2>&1 &&\n-- \n2.39.2\n\n"},{"id":"472735","messageId":"xmqq5ybpuzq7.fsf@gitster.g","threadId":"59283","inReplyTo":"20230225190526.21780-1-rybak.a.v@gmail.com","subject":"Re: [RFC PATCH v2] test-lib: drop comment about test_description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-02-25T22:50:08Z","receivedAt":"2023-02-25T22:50:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andrei Rybak <rybak.a.v@gmail.com> writes:\n\n> ...  The assignment\n> of \"test_description\" and the process of writing tests in general are\n> described in detail in \"t/README\".  So drop the obsolete comment.\n\nSounds sensible.\n\n> An alternative solution is to move the comment down to the usage of\n> variable \"test_description\".\n\nOr at the beginning, as the comment is about \"how you can use this\ntest-lib.sh test library in your tests\".\n\nI have no strong preference.  Just dropping it sounds easier, as a\nmore readable description already exists elsewhere.\n\n\n\n>  t/test-lib.sh | 6 ------\n>  1 file changed, 6 deletions(-)\n>\n> diff --git a/t/test-lib.sh b/t/test-lib.sh\n> index d272cca008..62136caee5 100644\n> --- a/t/test-lib.sh\n> +++ b/t/test-lib.sh\n> @@ -645,12 +645,6 @@ u200c=$(printf '\\342\\200\\214')\n>  \n>  export _x05 _x35 LF u200c EMPTY_TREE EMPTY_BLOB ZERO_OID OID_REGEX\n>  \n> -# Each test should start with something like this, after copyright notices:\n> -#\n> -# test_description='Description of this test...\n> -# This test checks if command xyzzy does the right thing...\n> -# '\n> -# . ./test-lib.sh\n>  test \"x$TERM\" != \"xdumb\" && (\n>  \t\ttest -t 1 &&\n>  \t\ttput bold >/dev/null 2>&1 &&\n"},{"id":"472745","messageId":"20230226105303.55033-1-rybak.a.v@gmail.com","threadId":"59283","inReplyTo":"20230225190526.21780-1-rybak.a.v@gmail.com","subject":"[PATCH v3] test-lib: drop comment about test_description","fromName":"Andrei Rybak","fromEmail":"rybak.a.v@gmail.com","sentAt":"2023-02-26T10:53:03Z","receivedAt":"2023-02-26T10:53:11Z","isPatch":true,"sender":{"key":"rybak.a.v@gmail.com","avatar":"https://avatars.githubusercontent.com/u/624072?v=4"},"body":"When a comment describing how each test file should start was added in\ncommit [1], it was the second comment of t/test-lib.sh.  The comment\ndescribes how variable \"test_description\" is supposed to be assigned at\nthe top of each test file and how \"test-lib.sh\" should be used by\nsourcing it.  However, even in [1], the comment was ten lines away from\nthe usage of the variable by test-lib.sh.  Since then, the comment has\ndrifted away both from the top of the file and from the usage of the\nvariable.  The comment just sits in the middle of the initialization of\nthe test library, surrounded by unrelated code, almost one hundred lines\naway from the usage of \"test_description\".\n\nNobody has noticed this drift during evolution of test-lib.sh, which\nsuggests that this comment has outlived its usefulness.  The assignment\nof \"test_description\", sourcing of \"test-lib.sh\" by tests, and the\nprocess of writing tests in general are described in detail in\n\"t/README\".  So drop the obsolete comment.\n\nAn alternative solution could be to move the comment either to the top\nof the file, or down to the usage of variable \"test_description\".\n\n[1] e1970ce43a (\"[PATCH 1/2] Test framework take two.\", 2005-05-13)\n\nSigned-off-by: Andrei Rybak <rybak.a.v@gmail.com>\n---\n\n  On 2023-02-25T23:50, Junio C Hamano wrote:\n  > Andrei Rybak <rybak.a.v@gmail.com> writes:\n  >> An alternative solution is to move the comment down to the usage of\n  >> variable \"test_description\".\n  > \n  > Or at the beginning, as the comment is about \"how you can use this\n  > test-lib.sh test library in your tests\".\n\nHere's v3 with updated description of the dropped comment and updated\ndescription of the alternative solution.\n\n  > I have no strong preference.  Just dropping it sounds easier, as a\n  > more readable description already exists elsewhere.\n\nAlso, at the top of \"test-lib.sh\", there is a comment pointing to that other\nplace:\n\n  # Test framework for git.  See t/README for usage.\n\nadded in c74c72034f (test: replace shebangs with descriptions in shell\nlibraries, 2013-11-25).\n\n t/test-lib.sh | 6 ------\n 1 file changed, 6 deletions(-)\n\ndiff --git a/t/test-lib.sh b/t/test-lib.sh\nindex d272cca008..62136caee5 100644\n--- a/t/test-lib.sh\n+++ b/t/test-lib.sh\n@@ -645,12 +645,6 @@ u200c=$(printf '\\342\\200\\214')\n \n export _x05 _x35 LF u200c EMPTY_TREE EMPTY_BLOB ZERO_OID OID_REGEX\n \n-# Each test should start with something like this, after copyright notices:\n-#\n-# test_description='Description of this test...\n-# This test checks if command xyzzy does the right thing...\n-# '\n-# . ./test-lib.sh\n test \"x$TERM\" != \"xdumb\" && (\n \t\ttest -t 1 &&\n \t\ttput bold >/dev/null 2>&1 &&\n-- \n2.39.2\n\n"}]}