{"thread":{"id":"60967","subject":"[PATCH v3] documentation: send-email: use camel case consistently","startedAt":"2024-02-20T22:01:27Z","lastAt":"2024-02-20T22:21:39Z","messageCount":5,"participants":["Dragan Simic","Junio C Hamano","Kristoffer Haugsbakk"],"isPatch":true,"patchVersion":3,"patchTotal":null},"messages":[{"id":"489027","messageId":"877b5bec11caa8a328ee0d4f226fe0666fd35a10.1708466383.git.dsimic@manjaro.org","threadId":"60967","inReplyTo":null,"subject":"[PATCH v3] documentation: send-email: use camel case consistently","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-20T22:01:21Z","receivedAt":"2024-02-20T22:01:27Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Correct a few random \"sendemail.*\" configuration parameter names in the\ndocumentation that, for some unknown reason and contrary to the expected,\ndidn't use camel case format.\n\nThe majority of the corrections are straightforward, by using camel case\nto denote boundaries of the individual words that, stringed together, make\nup configuration parameter names. A couple of abbreviations found in some\nof the corrected configuration parameter names present some exceptions,\nwhich are described in detail below.\n\nFirst, there's \"SSL\" as the abbreviation for \"Secure Sockets Layer\". [1]\nAs such, it's written using all uppercase letters, which is pretty much the\ngeneral rule for making abbreviations, with some exceptions. For example,\none rather well-known exception to this general rule is \"SoC\", which is the\nabbreviation for \"system-on-chip\". [2]\n\nSecond, there's \"Cc\" as the abbreviation for \"carbon copy\", which is another\nexception. As the acronym for \"carbon copy\", \"cc\" (mind the all lowercase\nletters) stems from the rather old times when, literally, carbon copies were\nmade. [3] Therefore, using \"CC\" (mind the all uppercase letters) or \"cc\"\n(mind the all lowercase letters) would be technically correct in the email\ndomain, as the abbreviation or as mentioned in RFC2076, [4] respectively, but\nthe age of email has established \"Cc\" (mind the mixed uppercase and lowercase\nletters) as some kind of de facto standard. [1][5][6] Moreover, some of the\ngit utilities, primarily git-send-email(1), already refer to making email\ncarbon copies as specifying \"Cc:\" email headers. As a result, \"Cc\" becomes\none of the exceptions to the general rule for making abbreviations.\n\n[1] https://en.wikipedia.org/wiki/Transport_Layer_Security\n[2] https://en.wikipedia.org/wiki/System_on_a_chip\n[3] https://en.wikipedia.org/wiki/Carbon_copy\n[4] https://datatracker.ietf.org/doc/html/rfc2076\n[5] https://bugzilla.mozilla.org/show_bug.cgi?id=212059\n[6] https://bugzilla.mozilla.org/show_bug.cgi?id=50826\n\nSigned-off-by: Dragan Simic \n---\n\nNotes:\n The version 3 includes further feedback from Junio, by adding a detailed\n rationale for using \"Cc\" instead of \"CC\", while also using \"SSL\", to the\n commit description. No code changes were introduced.\n \n The version 2 includes feedback from Junio, by changing \"Ssl\" to \"SSL\"\n in a couple of places where \"sendemail.smtpSSLCertPath\" is mentioned.\n There are already instances of \"SSL\" being used, for example in various\n \"http.proxySSL*\" configuration parameter names.\n\n Documentation/config/sendemail.txt | 12 ++++++------\n Documentation/git-send-email.txt | 18 +++++++++---------\n 2 files changed, 15 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt\nindex 7fc770ee9e69..6a869d67eb90 100644\n--- a/Documentation/config/sendemail.txt\n+++ b/Documentation/config/sendemail.txt\n@@ -8,7 +8,7 @@ sendemail.smtpEncryption::\n \tSee linkgit:git-send-email[1] for description. Note that this\n \tsetting is not subject to the 'identity' mechanism.\n \n-sendemail.smtpsslcertpath::\n+sendemail.smtpSSLCertPath::\n \tPath to ca-certificates (either a directory or a single file).\n \tSet it to an empty string to disable certificate verification.\n \n@@ -62,27 +62,27 @@ sendemail.chainReplyTo::\n sendemail.envelopeSender::\n sendemail.from::\n sendemail.headerCmd::\n-sendemail.signedoffbycc::\n+sendemail.signedOffByCc::\n sendemail.smtpPass::\n-sendemail.suppresscc::\n+sendemail.suppressCc::\n sendemail.suppressFrom::\n sendemail.to::\n-sendemail.tocmd::\n+sendemail.toCmd::\n sendemail.smtpDomain::\n sendemail.smtpServer::\n sendemail.smtpServerPort::\n sendemail.smtpServerOption::\n sendemail.smtpUser::\n sendemail.thread::\n sendemail.transferEncoding::\n sendemail.validate::\n sendemail.xmailer::\n \tThese configuration variables all provide a default for\n \tlinkgit:git-send-email[1] command-line options. See its\n \tdocumentation for details.\n \n-sendemail.signedoffcc (deprecated)::\n-\tDeprecated alias for `sendemail.signedoffbycc`.\n+sendemail.signedOffCc (deprecated)::\n+\tDeprecated alias for `sendemail.signedOffByCc`.\n \n sendemail.smtpBatchSize::\n \tNumber of messages to be sent per connection, after that a relogin\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex d1ef6a204e68..8264f8738093 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -138,7 +138,7 @@ Note that no attempts whatsoever are made to validate the encoding.\n \n --compose-encoding=::\n \tSpecify encoding of compose message. Default is the value of the\n-\t'sendemail.composeencoding'; if that is unspecified, UTF-8 is assumed.\n+\t'sendemail.composeEncoding'; if that is unspecified, UTF-8 is assumed.\n \n --transfer-encoding=(7bit|8bit|quoted-printable|base64|auto)::\n \tSpecify the transfer encoding to be used to send the message over SMTP.\n@@ -174,7 +174,7 @@ Sending\n \tSpecify a command to run to send the email. The command should\n \tbe sendmail-like; specifically, it must support the `-i` option.\n \tThe command will be executed in the shell if necessary. Default\n-\tis the value of `sendemail.sendmailcmd`. If unspecified, and if\n+\tis the value of `sendemail.sendmailCmd`. If unspecified, and if\n \t--smtp-server is also unspecified, git-send-email will search\n \tfor `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH.\n \n@@ -269,7 +269,7 @@ must be used for each option.\n \tcertificates concatenated together: see verify(1) -CAfile and\n \t-CApath for more information on these). Set it to an empty string\n \tto disable certificate verification. Defaults to the value of the\n-\t`sendemail.smtpsslcertpath` configuration variable, if set, or the\n+\t`sendemail.smtpSSLCertPath` configuration variable, if set, or the\n \tbacking SSL library's compiled-in default otherwise (which should\n \tbe the best choice on most platforms).\n \n@@ -313,7 +313,7 @@ Automating\n \tSpecify a command to execute once per patch file which\n \tshould generate patch file specific \"To:\" entries.\n \tOutput of this command must be single email address per line.\n-\tDefault is the value of 'sendemail.tocmd' configuration value.\n+\tDefault is the value of 'sendemail.toCmd' configuration value.\n \n --cc-cmd=::\n \tSpecify a command to execute once per patch file which\n@@ -348,19 +348,19 @@ Automating\n \n --[no-]signed-off-by-cc::\n \tIf this is set, add emails found in the `Signed-off-by` trailer or Cc: lines to the\n-\tcc list. Default is the value of `sendemail.signedoffbycc` configuration\n+\tcc list. Default is the value of `sendemail.signedOffByCc` configuration\n \tvalue; if that is unspecified, default to --signed-off-by-cc.\n \n --[no-]cc-cover::\n \tIf this is set, emails found in Cc: headers in the first patch of\n \tthe series (typically the cover letter) are added to the cc list\n-\tfor each email set. Default is the value of 'sendemail.cccover'\n+\tfor each email set. Default is the value of 'sendemail.ccCover'\n \tconfiguration value; if that is unspecified, default to --no-cc-cover.\n \n --[no-]to-cover::\n \tIf this is set, emails found in To: headers in the first patch of\n \tthe series (typically the cover letter) are added to the to list\n-\tfor each email set. Default is the value of 'sendemail.tocover'\n+\tfor each email set. Default is the value of 'sendemail.toCover'\n \tconfiguration value; if that is unspecified, default to --no-to-cover.\n \n --suppress-cc=::\n@@ -384,7 +384,7 @@ Automating\n - 'all' will suppress all auto cc values.\n --\n +\n-Default is the value of `sendemail.suppresscc` configuration value; if\n+Default is the value of `sendemail.suppressCc` configuration value; if\n that is unspecified, default to 'self' if --suppress-from is\n specified, as well as 'body' if --no-signed-off-cc is specified.\n \n@@ -471,7 +471,7 @@ Information\n \tInstead of the normal operation, dump the shorthand alias names from\n \tthe configured alias file(s), one per line in alphabetical order. Note\n \tthat this only includes the alias name and not its expanded email addresses.\n-\tSee 'sendemail.aliasesfile' for more information about aliases.\n+\tSee 'sendemail.aliasesFile' for more information about aliases.\n \n \n CONFIGURATION\n"},{"id":"489028","messageId":"xmqq1q96okkb.fsf@gitster.g","threadId":"60967","inReplyTo":"877b5bec11caa8a328ee0d4f226fe0666fd35a10.1708466383.git.dsimic@manjaro.org","subject":"Re: [PATCH v3] documentation: send-email: use camel case consistently","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-20T22:08:36Z","receivedAt":"2024-02-20T22:08:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Dragan Simic writes:\n\n> general rule for making abbreviations, with some exceptions. For example,\n> one rather well-known exception to this general rule is \"SoC\", which is the\n> abbreviation for \"system-on-chip\". [2]\n\nI am not opposed to say \"we allow spelling 'carbon copy' as 'Cc'\nbecause too many people mistakenly use that capitalization pattern\",\nwhich is what you earlier said, though. As I said, I do not insist\none or the other capitalization, as long as it is backed by solid\nreasoning that would not confuse future developers.\n\nIt is very common to omit upcasing prepositions, articles, etc. when\nspelling acronyms in all capital, so \"SoC\" would not count as a good\nexample of an exception. That's the kind of bogus justification of\ngiving an exception to \"Cc\" I would rather want to avoid. It really\nis only \"Cc\" that needs to justify exception in your patch.\n\n\n\n\n\n"},{"id":"489029","messageId":"59cb804a0221038626f16a4b0138e3eb@manjaro.org","threadId":"60967","inReplyTo":"xmqq1q96okkb.fsf@gitster.g","subject":"Re: [PATCH v3] documentation: send-email: use camel case consistently","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-20T22:17:14Z","receivedAt":"2024-02-20T22:17:16Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-02-20 23:08, Junio C Hamano wrote:\n> Dragan Simic writes:\n> \n>> general rule for making abbreviations, with some exceptions. For \n>> example,\n>> one rather well-known exception to this general rule is \"SoC\", which \n>> is the\n>> abbreviation for \"system-on-chip\". [2]\n> \n> I am not opposed to say \"we allow spelling 'carbon copy' as 'Cc'\n> because too many people mistakenly use that capitalization pattern\",\n> which is what you earlier said, though. As I said, I do not insist\n> one or the other capitalization, as long as it is backed by solid\n> reasoning that would not confuse future developers.\n> \n> It is very common to omit upcasing prepositions, articles, etc. when\n> spelling acronyms in all capital, so \"SoC\" would not count as a good\n> example of an exception. That's the kind of bogus justification of\n> giving an exception to \"Cc\" I would rather want to avoid. It really\n> is only \"Cc\" that needs to justify exception in your patch.\n\nAlright, let's try v4 with no such examples.\n"},{"id":"489030","messageId":"37c0c025-7120-49f3-bc2f-f35249339f3a@app.fastmail.com","threadId":"60967","inReplyTo":"877b5bec11caa8a328ee0d4f226fe0666fd35a10.1708466383.git.dsimic@manjaro.org","subject":"Re: [PATCH v3] documentation: send-email: use camel case consistently","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2024-02-20T22:17:47Z","receivedAt":"2024-02-20T22:18:08Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Tue, Feb 20, 2024, at 23:01, Dragan Simic wrote:\n> Correct a few random \"sendemail.*\" configuration parameter names in the\n> documentation that, for some unknown reason and contrary to the expected,\n> didn't use camel case format.\n\nInteresting. Consistency is good. Nice work.\n\nPS: Please keep me on CC. I’m not subscribed to the list.\n\nPPS: 😉\n\n-- \nKristoffer Haugsbakk\n\n"},{"id":"489031","messageId":"112df7b4122155b8021134367fc0e458@manjaro.org","threadId":"60967","inReplyTo":"37c0c025-7120-49f3-bc2f-f35249339f3a@app.fastmail.com","subject":"Re: [PATCH v3] documentation: send-email: use camel case consistently","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-20T22:21:37Z","receivedAt":"2024-02-20T22:21:39Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-02-20 23:17, Kristoffer Haugsbakk wrote:\n> On Tue, Feb 20, 2024, at 23:01, Dragan Simic wrote:\n>> Correct a few random \"sendemail.*\" configuration parameter names in \n>> the\n>> documentation that, for some unknown reason and contrary to the \n>> expected,\n>> didn't use camel case format.\n> \n> Interesting. Consistency is good. Nice work.\n> \n> PS: Please keep me on CC. I’m not subscribed to the list.\n\nSure, here comes the v4 to you as a virtual carbon copy. :)\n"}]}