documentation: guide of best practices for GIT developer
cover documentation: guide of best practices for GIT developer
Hello,
This patch has for purpose to introduce a file where GIT developers can share their own best practices, tools or workflows to the community in order to help the GIT developer.
The discussion about this idea begin in this thread:
Message-Id: <[email protected]>
Derrick Stolee and I agreed that is can be a good idea.
And, I think, it can help a newcomer, but not necessarily people with a lot of experience on various projects. But, we can give it a try and see where it goes.
PS:
I do not believe it is a good idea to give detailed tutorials because there are a lot on the internet. However, give the reader pros, cons and curiosity to test those tools, practice or workflow can be really good.
It's better if the tools are open source and free, but it is not mandatory.
Sincerly,
Cogoni Guillaume
COGONI Guillaume (1):
documentation: guide of best practices for GIT developer
Documentation/Makefile | 1 + Documentation/WorkingOnGit.txt | 53 ++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 Documentation/WorkingOnGit.txt
base-commit: ab1f2765f78e75ee51dface57e1071b3b7f42b09
Signature · 1 line
2.25.1
PATCH 1/1 documentation: guide of best practices for GIT developer
The purpose of this guide is to have a place where GIT developer can share their own best practices, tools or workflows to the community in order to help the GIT developer.
--- Documentation/Makefile | 1 + Documentation/WorkingOnGit.txt | 53 ++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 Documentation/WorkingOnGit.txt
Documentation/Makefile +1 -0
@@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += WorkingOnGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol
Documentation/WorkingOnGit.txt new file +53 -0
53 lines not on this page · raw message
Signature · 1 line
2.25.1
Quoted 6 lines · COGONI Guillaume
Hello,
This patch has for purpose to introduce a file where GIT developers can share their own best practices, tools or workflows to the community in order to help the GIT developer.
Wouldn't there be a possibility that this doc can degrade into a list of personal taste? I think the rules that new developers *should* know have already been documented in 'MyFirstContribution.txt' or 'SubmittingPatches' and things like that. If there is a *common* recommended practice, if not "their own", I guess it can be added into existing documentations.
Quoted 8 lines
The discussion about this idea begin in this thread:
Message-Id: <[email protected]>Derrick Stolee and I agreed that is can be a good idea.
And, I think, it can help a newcomer, but not necessarily people with a lot of experience on various projects. But, we can give it a try and see where it goes.
Quoted 4 lines
PS:
I do not believe it is a good idea to give detailed tutorials because there are a lot on the internet. However, give the reader pros, cons and curiosity to test those tools, practice or workflow can be really good.
The tools that people use can vary in an incredible way, thus the workflow defined by multiple tools can go even further. I think a workflow here is highly opinionated, and such a thing may disturb newcomers?
Wouldn't it be better to let people decide on their own tools and Git should stay
respectful? Let alone most people come into the community as developer, if they are going to be "WorkingOnGit", so they may already be well-suited in their own workflow?
Signature · 2 lines
Thanks & Regards, Shaoxuan
Quoted 2 lines · Shaoxuan Yuan
Wouldn't there be a possibility that this doc can degrade into a list of personal taste?
Of course, it could end like this, if someone writes something in this document, it's because that person likes it. People are not going to recommend something they don't use. But, I also think that it's not really bad because the purpose it's to have a bunch of tools that might interest others.
Quoted 3 lines
The tools that people use can vary in an incredible way, thus the workflow defined by multiple tools can go even further. I think a workflow here is highly opinionated, and such a thing may disturb newcomers?
Yup, you got a point, it's a bit complicated to recommend a workflow because there is a lot of variety. But, about tools, it's possible because you just say how this tool can be useful for the project. In my first recommendation I propose the built-in debugger of VS Code and say that "It can be used to isolate certain parts of code, with this you may be able to ask more precise questions when you are stuck.". I think that recommendation may not disturb newcomers or other Git developers because it's only a tip, use the tool or not, you have the choice.
Quoted 2 lines
Wouldn't it be better to let people decide on their own tools and Git should stay respectful?
It's just a tool recommendation, and I don't force anyone to use it. Is it the name of the file "WorkingOnGit" that makes you think it's a mandatory thing? Maybe "HelpToolForGit" is better?
Quoted 3 lines
Let alone most people come into the community as
developer, if they are going to be "WorkingOnGit", so they may already be well-suited in their own workflow?
Yes, naturally, but even if people have their own workflow with this tool or this tool, maybe if you recommend a tool that is "better" for working on Git, will they change their habits? But, as I said it's just a recommendation, the final choice of whether to use it or not, is up to them.
Thanks, I appreciate your answer and I hope I've answered your questions. I think simply recommending tools is a good thing, because, as you mentioned, recommending a workflow is complicated.
SIncerely,
COGONI Guillaume
cover Documentation/ToolsOnGit.txt: gather information about tools
I decide to change my approach with this patch, and now I agreed at some point with <[email protected]>, GIT might not be the right place to talk about recommendation for best practice, tools or workflows. So, I change the file, it just gathers some links that point to tools that have a README or scripts in contrib/.
Now, the idea is more like "Oh, you use this tool? Did you know that we have a README and some scripts to make it more simple to use along GIT, it might interest you." (e.g. see contrib/emacs.). It's just informative and no longer a recommendation.
In addition, having a file that collects this type of information is more practical that have a tool mention in many files. And I hope that people who use other tools other than Emacs or Visual Studio Code, will be interesting for doing scripts and README in contrib/.
Thanks and I hope this new approach is better,
COGONI Guillaume
Desmoniak (1):
Documentation/ToolsOnGit.txt: gather information
Documentation/Makefile | 1 + Documentation/ToolsOnGit.txt | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 Documentation/ToolsOnGit.txt
Difference between v0 and v1
Documentation/Makefile +1 -1
@@ -93,7 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches -TECH_DOCS += WorkingOnGit +TECH_DOCS += ToolsOnGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol
Documentation/ToolsOnGit.txt new file +35 -0
@@ -0,0 +1,35 @@ +Tools on GIT +============ +:sectanchors: + +[[summary]] +== Summary + +This document aims to gather tools that have a README and/or scripts in +the GIT project. + +[[author]] +=== Author + +The Git community. + +[[table_of_contents]] +== Table of contents + +- <<vscode>> +- <<emacs>> + +[[vscode]] +=== Visual Studio Code (VS Code) + +The contrib/vscode/init.sh script creates configuration files that enable +several valuable VS Code features. See contrib/vscode/README.md for more +information on using the script. + +In particular, this script enables using the VS Code visual debugger, including +setting breakpoints, logpoints, conditional breakpoints and more in the editor. + +[[emacs]] +=== Emacs + +See contrib/emacs/README for more information.
Documentation/WorkingOnGit.txt deleted +0 -53
53 lines not on this page · raw message
2.25.1
PATCH 1/1 Documentation/ToolsOnGit.txt: gather information about tools
This document aims to gather tools that have a README and/or scripts in the GIT project in order to simplify the search of information for a particular tool.
--- Documentation/Makefile | 1 + Documentation/ToolsOnGit.txt | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 Documentation/ToolsOnGit.txt
Documentation/Makefile +1 -0
@@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += ToolsOnGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol
Documentation/ToolsOnGit.txt new file +35 -0
@@ -0,0 +1,35 @@ +Tools on GIT +============ +:sectanchors: + +[[summary]] +== Summary + +This document aims to gather tools that have a README and/or scripts in +the GIT project. + +[[author]] +=== Author + +The Git community. + +[[table_of_contents]] +== Table of contents + +- <<vscode>> +- <<emacs>> + +[[vscode]] +=== Visual Studio Code (VS Code) + +The contrib/vscode/init.sh script creates configuration files that enable +several valuable VS Code features. See contrib/vscode/README.md for more +information on using the script. + +In particular, this script enables using the VS Code visual debugger, including +setting breakpoints, logpoints, conditional breakpoints and more in the editor. + +[[emacs]] +=== Emacs + +See contrib/emacs/README for more information.
Signature · 1 line
2.25.1
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools
Quoted 2 lines · COGONI Guillaume
This document aims to gather tools that have a README and/or scripts in the GIT project
We usually spell the project name as Git, and the command name as git. And nothing as GIT ;-).
Documentation/Makefile SP_ARTICLES += $(API_DOCS) · line 96
Quoted 7 lines
Documentation/Makefile +0
-0@@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += ToolsOnGit
If the goal is to document tools that can be used to develop Git itself, probably ToolsForGit would be more appropriate...
Documentation/ToolsOnGit.txt line 2
Quoted 5 lines
Documentation/ToolsOnGit.txt new file +2
-0@@ -0,0 +1,35 @@ +Tools on GIT +============
... and "Tools for developing Git" a better long title?
Documentation/ToolsOnGit.txt
Quoted 3 lines
Documentation/ToolsOnGit.txt new file +3
-0+== Summary + +This document aims to gather tools that have a README and/or scripts in > +the GIT project.
I don't think having a README should be the criterion here. To me the criterion should be "tools that may not work out of the box, but for which some explanation, configuration or script allow using the tool properly".
Quoted 10 lines
Documentation/ToolsOnGit.txt new file +10
-0+[[author]] +=== Author + +The Git community. + +[[table_of_contents]] +== Table of contents + +- <<vscode>> +- <<emacs>>
Documentation/ToolsOnGit.txt line 30
Quoted 10 lines
Documentation/ToolsOnGit.txt new file +10
-0+ +[[vscode]] +=== Visual Studio Code (VS Code) + +The contrib/vscode/init.sh script creates configuration files that enable +several valuable VS Code features. See contrib/vscode/README.md for more +information on using the script. + +In particular, this script enables using the VS Code visual debugger, including +setting breakpoints, logpoints, conditional breakpoints and more in the editor.
I don't think the last sentence is needed, and if it is, it would be better within contrib/vscode/README.md (so that someone reaching this README directly do see the information too).
Documentation/ToolsOnGit.txt line 35
Quoted 4 lines
Documentation/ToolsOnGit.txt new file +4
-0+[[emacs]] +=== Emacs + +See contrib/emacs/README for more information.
This README starts with "This directory used to contain ..." (note the "used to". There's no reason to point the user to obsolete scripts.
Also, the stuff that used to be in this directory do not fall in the same category. They were targeted at users of both Git and Emacs, but not specifically to develop Git itself.
OTOH, CodingGuidelines's suggestion to configure Emacs like this is IMHO typically something that could appear in this document:
- For Emacs, it's useful to put the following in GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:
;; note the first part is useful for C editing, too
((nil . ((indent-tabs-mode . t)
(tab-width . 8)
(fill-column . 80)))
(cperl-mode . ((cperl-indent-level . 8)
(cperl-extra-newline-before-brace . nil)
(cperl-merge-trailing-else . t))))Actually, the Linux kernel's CodingStyle contains more relevant stuff (for C, not Perl):
https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it
(But aren't all Git devs former kernel developers? ;-) )
Cheers,
Signature · 2 lines
Matthieu Moy https://matthieu-moy.fr/
Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools
Quoted 10 lines · Matthieu Moy
Quoted 5 lines
+== Summary
(quoted diff) +2
-0+ +This document aims to gather tools that have a README and/or scriptsin > +the GIT project.
I don't think having a README should be the criterion here. To me the criterion should be "tools that may not work out of the box, but for which some explanation, configuration or script allow using the tool properly".
I'm of the view that a README is a positive indicator that there is some informational value regarding the tool's use for developing Git being made available. It doesn't always have to be code before it is of assistance in developing Git.
Just my £0.02.
--
Philip
Re: [PATCH v1 1/1] Documentation/ToolsOnGit.txt: gather information about tools
In reply to Matthieu MoyQuoted 2 lines · Matthieu Moy
Actually, the Linux kernel's CodingStyle contains more relevant stuff (for C, not Perl):
True.
Quoted 3 lines
https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it
(But aren't all Git devs former kernel developers? ;-) )
It's 2022, Matthieu, not 2005 ;-).
Thanks for a helpful and useful review.
v2 cover Documentation/ToolsForGit.txt: Tools for developing Git
Quoted 3 lines · MOY Matthieu
I don't think the last sentence is needed, and if it is, it would be better within
contrib/vscode/README.md(so that someone reaching this README directly do see the information too).
I think so too. However, I already make a PATCH last week for contrib/vscode/README:
(see <[email protected]>). And, I see that in What's cooking in git.git (Apr 2022, #04; Thu, 14) it will be merge in Next. So, do I take this PATCH from the last week and I add it this part in contrib/vscode/README or I just add this part here in this new PATCH but where the subject is different?
Quoted 11 lines
- For Emacs, it's useful to put the following in GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:
;; note the first part is useful for C editing, too ((nil . ((indent-tabs-mode . t) (tab-width . 8) (fill-column . 80))) (cperl-mode . ((cperl-indent-level . 8) (cperl-extra-newline-before-brace . nil) (cperl-merge-trailing-else . t))))
Quoted 4 lines
Actually, the Linux kernel's CodingStyle contains more relevant stuff (for C, not Perl):
https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it
I add this part directly in ToolsForGit.txt and not in the README in contrib/emacs. But, from this document in Documentation/RelNotes/2.18.0.txt, I read this:
"The scripts in contrib/emacs/ have outlived their usefulness and have been replaced with a stub that errors out and tells the user there are replacements." So, for the next version of this PATCH, can I replace what is in the README by the configuration that I write in ToolsForGit.txt?
Quoted 4 lines · OAKLEY Philip
I'm of the view that a README is a positive indicator that there is some informational value regarding the tool's use for developing Git being made available. It doesn't always have to be code before it is of assistance in developing Git.
I agreed with OAKLEY, the README is good indicator to say that we have some information besides the scripts.
COGONI Guillaume (1):
Documentation/ToolsForGit.txt: Tools for developing Git
Documentation/CodingGuidelines | 11 ----- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 79 ++++++++++++++++++++++++++++++++++ 3 files changed, 80 insertions(+), 11 deletions(-) create mode 100644 Documentation/ToolsForGit.txt
Difference between v1 and v2
Documentation/ToolsForGit.txt renamed from Documentation/ToolsOnGit.txt +48 -4
@@ -1,12 +1,12 @@ -Tools on GIT -============ +Tools for developing Git +======================== :sectanchors: [[summary]] == Summary This document aims to gather tools that have a README and/or scripts in -the GIT project. +the Git project. [[author]] === Author
@@ -32,4 +32,48 @@ setting breakpoints, logpoints, conditional breakpoints and more in the editor. [[emacs]] === Emacs -See contrib/emacs/README for more information. +- To follow rules of the CodingGuideline, it's useful to put the following in +GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: +---- +;; note the first part is useful for C editing, too +((nil . ((indent-tabs-mode . t) + (tab-width . 8) + (fill-column . 80))) + (cperl-mode . ((cperl-indent-level . 8) + (cperl-extra-newline-before-brace . nil) + (cperl-merge-trailing-else . t)))) +---- + +- The version for C: +---- +(defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + +(add-hook 'c-mode-common-hook + (lambda () + ;; Add kernel style + (c-add-style + "linux-tabs-only" + '("linux" (c-offsets-alist + (arglist-cont-nonempty + c-lineup-gcc-asm-reg + c-lineup-arglist-tabs-only)))))) + +(add-hook 'c-mode-hook + (lambda () + (let ((filename (buffer-file-name))) + ;; Enable kernel mode for the appropriate files + (when (and filename + (string-match (expand-file-name "~/src/linux-trees") + filename)) + (setq indent-tabs-mode t) + (setq show-trailing-whitespace t) + (c-set-style "linux-tabs-only"))))) +---- +
Documentation/CodingGuidelines +0 -11
@@ -492,17 +492,6 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: - - ;; note the first part is useful for C editing, too - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) - For Python scripts: - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).
Signature · 1 line
2.25.1
PATCH v2 1/1 Documentation/ToolsForGit.txt: Tools for developing Git
This document aims to gather tools that have a README and/or scripts in the GIT project in order to simplify the search of information for a particular tool.
Move the part about Emacs configuration from CodingGuidelines to ToolsForGit.txt because it's the purpose of the new file centralize the information about tools.
--- Documentation/CodingGuidelines | 11 ----- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 79 ++++++++++++++++++++++++++++++++++ 3 files changed, 80 insertions(+), 11 deletions(-) create mode 100644 Documentation/ToolsForGit.txt
Documentation/CodingGuidelines +0 -11
@@ -492,17 +492,6 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: - - ;; note the first part is useful for C editing, too - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) - For Python scripts: - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).
Documentation/Makefile +1 -0
@@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += ToolsForGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol
Documentation/ToolsForGit.txt new file +79 -0
79 lines not on this page · raw message
Signature · 1 line
2.25.1
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH v2 0/1] Documentation/ToolsForGit.txt: Tools for developing Git
Quoted 9 lines · COGONI Guillaume
Quoted 6 lines · MOY Matthieu
Documentation/ToolsOnGit.txt line 30
Quoted 2 lines
Documentation/ToolsOnGit.txt new file +2
-0+In particular, this script enables using the VS Code visual debugger, including +setting breakpoints, logpoints, conditional breakpoints and more in the editor.I don't think the last sentence is needed, and if it is, it would be better within
contrib/vscode/README.md(so that someone reaching this README directly do see the information too).
Quoted 7 lines
I think so too. However, I already make a PATCH last week for contrib/vscode/README:
(see <[email protected]>). And, I see that in What's cooking in git.git (Apr 2022, #04; Thu, 14) it will be merge in Next. So, do I take this PATCH from the last week and I add it this part in contrib/vscode/README or I just add this part here in this new PATCH but where the subject is different?
I think you can just drop that sentence. For someone a bit familiar with either VS code or any other IDE, it's no big surprise that the debugger integration allows such feature. For someone not familiar with VS code, the patch about to land in next already contains a link to a page explaining that.
If you want to add more explanation, then I think it should be added to contrib/vscode/README. You will probably want to add in next to the lines touched by the previous patch, hence either Junio will have to solve a conflict, or you need to write your patch on top of the previous one.
Quoted 14 lines
Quoted 13 lines
- For Emacs, it's useful to put the following in
GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: ;; note the first part is useful for C editing, too ((nil . ((indent-tabs-mode . t) (tab-width . 8) (fill-column . 80))) (cperl-mode . ((cperl-indent-level . 8) (cperl-extra-newline-before-brace . nil) (cperl-merge-trailing-else . t))))Actually, the Linux kernel's CodingStyle contains more relevant stuff (for C, not Perl):
Quoted 8 lines
Quoted 1 line
https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it
I add this part directly in ToolsForGit.txt and not in the README in contrib/emacs. But, from this document in
Documentation/RelNotes/2.18.0.txt, I read this:
"The scripts in contrib/emacs/ have outlived their usefulness and have been replaced with a stub that errors out and tells the user there are replacements." So, for the next version of this PATCH, can I replace what is in the README by the configuration that I write in ToolsForGit.txt?
contrib/emacs was really not meant for developers hacking on Git. Since it contains only pointers to obsolete stuff, we may want to just discard its current content and make it the place to put documentation for people hacking on Git with Emacs, just like contrib/vscode/ is for VS code and Git. But we probably have only a few (tens of) lines of documentation, so adding the doc directly in ToolsForGit.txt is probably better.
Quoted 9 lines
Quoted 4 lines · OAKLEY Philip
I'm of the view that a README is a positive indicator that there is some informational value regarding the tool's use for developing Git being made available. It doesn't always have to be code before it is of assistance in developing Git.
I agreed with OAKLEY, the README is good indicator to say that we have some information besides the scripts.
A good indicator, yes. But reading only the summary ...
Quoted 4 lines
== Summary
This document aims to gather tools that have a README and/or scripts in the Git project.
I have no idea whether this document's audience is "people hacking ON Git's codebase" or "people using Git (somewhere else)". I believe the first sentences of the document should answer "is this document for me?" (i.e. "shall I continue reading?"), and currently it doesn't.
Saying instead something like
This documents gathers tips, scripts and configuration file to help people working on Git's codebase use their favorite tools while following Git's coding style.
would make the target audience much clearer IMHO.
Review
Quoted 13 lines
+- To follow rules of the CodingGuideline, it's useful to put the following in
(quoted diff) +12
-0+GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: +---- +;; note the first part is useful for C editing, too +((nil . ((indent-tabs-mode . t) + (tab-width . 8) + (fill-column . 80))) + (cperl-mode . ((cperl-indent-level . 8) + (cperl-extra-newline-before-brace . nil) + (cperl-merge-trailing-else . t)))) +---- + +- The version for C:
The version for Perl already contains some configuration applicable to C (indent-tabs-mode, tab-width and fill-column).
Review
Quoted 6 lines
(quoted diff) +6
-0+(add-hook 'c-mode-hook + (lambda () + (let ((filename (buffer-file-name))) + ;; Enable kernel mode for the appropriate files + (when (and filename + (string-match (expand-file-name "~/src/linux-trees")
This works only if the user checked out Git's source code in ~/src/linux-trees, which is unlikely ;-). I guess this path is not to be taken literally (i.e. it's more clearly "adapt the configuration to your actual directory layout"), but using linux-trees here won't make it clear that it should be the place to Git's source code.
Review
Quoted 2 lines
(quoted diff) +2
-0+ filename)) + (setq indent-tabs-mode t)
This one is redundant with the above for example.
Actually, while the tips given in Linux's kernel CodingStyle are relevant for us, I'm not sure copy-pasting them in Git's tree actually has added value. We may as well just link to them, like
For a more complete setup, since Git's codebase uses a coding style similar to the Linux kernel's style, tips given in Linux's CodingStyle document can be applied here too.
(Plus a link to the file on kernel.org)
If you copy paste here, you should cite the source and say stg like "This is adapted from Linux's suggestion in its CodingStyle document".
Documentation/CodingGuidelines For Perl programs: · line 497
Quoted 9 lines
Documentation/CodingGuidelines +0
-3@@ -492,17 +492,6 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: -
I agree that removing Emacs-specific code from a general document is nice, but then you should replace it with a link to ToolsForGit.txt like "Tips to make your editor follow this style can be found in ToolsForGit.txt" (without being specific to Emacs, that's the point of the document, it also applies to VS code and may be extended in the future to other editors).
Cheers,
Signature · 2 lines
Matthieu Moy https://matthieu-moy.fr/
v3 cover Documentation/ToolsForGit.txt: Tools for developing Git
Quoted 5 lines · MOY Matthieu
I think you can just drop that sentence. For someone a bit familiar with either VS code or any other IDE, it's no big surprise that the debugger integration allows such feature. For someone not familiar with VS code, the patch about to land in next already contains a link to a page explaining that.
Finally, I drop that sentence, I also think that the link that I put in contrib/vscode/README is sufficient.
Quoted 7 lines
contrib/emacs was really not meant for developers hacking on Git. Since it contains only pointers to obsolete stuff, we may want to just discard its current content and make it the place to put documentation for people hacking on Git with Emacs, just like contrib/vscode/ is for VS code and Git. But we probably have only a few (tens of) lines of documentation, so adding the doc directly in ToolsForGit.txt is probably better.
I left everything as they were. I just add the configuration lines directly in ToolsForGit.txt because there is not a lot of line.
But, in the future, if there is more line, it would be better to move all of this in the contrib/emacs/README.
Quoted 1 line
A good indicator, yes. But reading only the summary ...
I take the summary that you propose, so this not a criterion now.
Quoted 6 lines
I agree that removing Emacs-specific code from a general document is nice, but then you should replace it with a link to ToolsForGit.txt like "Tips to make your editor follow this style can be found in ToolsForGit.txt" (without being specific to Emacs, that's the point of the document, it also applies to VS code and may be extended in the future to other editors).
Yup, I fix this, I add a mention to Documentation/ToolsForGit.txt in CodingGuideline. I add it at the end of the file.
Thanks for your review,
COGONI Guillaume.
COGONI Guillaume (1):
Documentation/ToolsForGit.txt: Tools for developing Git
Documentation/CodingGuidelines | 18 +++++------- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+), 11 deletions(-) create mode 100644 Documentation/ToolsForGit.txt
Interdiff versus v2 :
Documentation/CodingGuidelines +7 -0
@@ -722,3 +722,10 @@ Writing Documentation: inline substituted text+ instead of `monospaced literal text`, and with the former, the part that should not get substituted must be quoted/escaped. + + +Documentation/ToolsForGit.txt: + + This document collects tips, scripts, and configuration files to help + contributors working with the Git codebase use their favorite tools while + following the Git coding style.
Documentation/ToolsForGit.txt +9 -34
59 lines not on this page · raw message
Signature · 1 line
2.25.1
PATCH v3 1/1 Documentation/ToolsForGit.txt: Tools for developing Git
This document gathers tips, scripts and configuration file to help people working on Git’s codebase use their favorite tools while following Git’s coding style.
Move the part about Emacs configuration from CodingGuidelines to ToolsForGit.txt because it's the purpose of the new file centralize the information about tools.
But, add a mention to Documentation/ToolsForGit.txt in CodingGuidelines because there is also information about the coding style in it.
--- Documentation/CodingGuidelines | 18 +++++------- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+), 11 deletions(-) create mode 100644 Documentation/ToolsForGit.txt
Documentation/CodingGuidelines +7 -11
@@ -492,17 +492,6 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: - - ;; note the first part is useful for C editing, too - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) - For Python scripts: - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).
@@ -733,3 +722,10 @@ Writing Documentation: inline substituted text+ instead of `monospaced literal text`, and with the former, the part that should not get substituted must be quoted/escaped. + + +Documentation/ToolsForGit.txt: + + This document collects tips, scripts, and configuration files to help + contributors working with the Git codebase use their favorite tools while + following the Git coding style.
Documentation/Makefile +1 -0
@@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += ToolsForGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol
Documentation/ToolsForGit.txt new file +51 -0
51 lines not on this page · raw message
Signature · 1 line
2.25.1
Re: [PATCH v3 1/1] Documentation/ToolsForGit.txt: Tools for developing Git
Quoted 9 lines · COGONI Guillaume
Documentation/CodingGuidelines +0
-1@@ -492,17 +492,6 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in
Documentation/CodingGuidelines For Perl programs: · line 505
Quoted 10 lines
Documentation/CodingGuidelines +0
-10- GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: - - ;; note the first part is useful for C editing, too - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) -
Moving this out is OK as long as it is clear to readers of this document that they can refer to the other one for tool specific tips.
Documentation/CodingGuidelines Writing Documentation: · line 731
Quoted 12 lines
Documentation/CodingGuidelines +7
-0- We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).@@ -733,3 +722,10 @@ Writing Documentation: inline substituted text+ instead of `monospaced literal text`, and with the former, the part that should not get substituted must be quoted/escaped. + + +Documentation/ToolsForGit.txt: + + This document collects tips, scripts, and configuration files to help + contributors working with the Git codebase use their favorite tools while + following the Git coding style.
This looks strangely out of place. The preceding "sections" of this document are
- general coding principle
- specific guidelines for each language.
- how output should read
- how error messages should read
- how configuration variables are named
- how documentation pages are written
The name of a single document and explanation on what is in it does not make a good new entry in that existing list.
If we must mention the existence of this document in the guidelines doc, I have a feeling that a better place might be near the preface of the second item, e.g.
Documentation/CodingGuidelines +4 -1
@@ -43,7 +43,10 @@ the overall style of existing code. Modifications to existing code is expected to match the style the surrounding code already uses (even if it doesn't match the overall style of existing code). -But if you must have a list of rules, here they are. +But if you must have a list of rules, here are some language +specific ones. Note that Documentation/ToolsForGit document +has a collection of tips to help you use some external tools +to conform to these guidelines. For shell scripts specifically (not exhaustive):
v4 cover Documentation/ToolsForGit.txt: Tools for developing Git
Hello,
Thanks for your review Junio C Hamano.
COGONI Guillaume (1):
Documentation/ToolsForGit.txt: Tools for developing Git
Documentation/CodingGuidelines | 16 +++-------- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 12 deletions(-) create mode 100644 Documentation/ToolsForGit.txt
Interdiff against v3:
Documentation/CodingGuidelines +4 -8
@@ -43,7 +43,10 @@ the overall style of existing code. Modifications to existing code is expected to match the style the surrounding code already uses (even if it doesn't match the overall style of existing code). -But if you must have a list of rules, here they are. +But if you must have a list of rules, here are some language +specific ones. Note that Documentation/ToolsForGit.txt document +has a collection of tips to help you use some external tools +to conform to these guidelines. For shell scripts specifically (not exhaustive):
@@ -722,10 +725,3 @@ Writing Documentation: inline substituted text+ instead of `monospaced literal text`, and with the former, the part that should not get substituted must be quoted/escaped. - - -Documentation/ToolsForGit.txt: - - This document collects tips, scripts, and configuration files to help - contributors working with the Git codebase use their favorite tools while - following the Git coding style.
Signature · 1 line
2.25.1
PATCH v4 1/1 Documentation/ToolsForGit.txt: Tools for developing Git
This document gathers tips, scripts and configuration file to help people working on Git’s codebase use their favorite tools while following Git’s coding style.
Move the part about Emacs configuration from CodingGuidelines to ToolsForGit.txt because it's the purpose of the new file centralize the information about tools.
But, add a mention to Documentation/ToolsForGit.txt in CodingGuidelines because there is also information about the coding style in it.
--- Documentation/CodingGuidelines | 16 +++-------- Documentation/Makefile | 1 + Documentation/ToolsForGit.txt | 51 ++++++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 12 deletions(-) create mode 100644 Documentation/ToolsForGit.txt
Documentation/CodingGuidelines +4 -12
@@ -43,7 +43,10 @@ the overall style of existing code. Modifications to existing code is expected to match the style the surrounding code already uses (even if it doesn't match the overall style of existing code). -But if you must have a list of rules, here they are. +But if you must have a list of rules, here are some language +specific ones. Note that Documentation/ToolsForGit.txt document +has a collection of tips to help you use some external tools +to conform to these guidelines. For shell scripts specifically (not exhaustive):
@@ -492,17 +495,6 @@ For Perl programs: - Learn and use Git.pm if you need that functionality. - - For Emacs, it's useful to put the following in - GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: - - ;; note the first part is useful for C editing, too - ((nil . ((indent-tabs-mode . t) - (tab-width . 8) - (fill-column . 80))) - (cperl-mode . ((cperl-indent-level . 8) - (cperl-extra-newline-before-brace . nil) - (cperl-merge-trailing-else . t)))) - For Python scripts: - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/).
Documentation/Makefile +1 -0
@@ -93,6 +93,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += ToolsForGit TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol
Documentation/ToolsForGit.txt new file +51 -0
51 lines not on this page · raw message
Signature · 1 line
2.25.1