On 3/1/2018 11:44 PM, Jonathan Nieder wrote:
Hi,
Derrick Stolee wrote:
Now, we'd like to make that document publicly available. These steps are
focused on a Windows user, so we propose putting them in the
git-for-windows/git repo under CONTRIBUTING.md. I have a pull request open
for feedback [1]. I'll read comments on that PR or in this thread.
Thanks! I wonder if we can put this in the standard Documentation/
directory as well. E.g. the Windows CONTRIBUTING.md could say say
"See Documentation/Contributing-On-Windows.md" so that the bulk of the
text would not have to be git-for-windows specific.
That's a good idea. After this review stabilizes, I'll send a patch to
add the windows-specific instructions as you recommend.
What precedent do we have for referencing forks like git-for-windows/git?
[...]
+++ b/CONTRIBUTING.md
@@ -0,0 +1,401 @@
+How to Contribute to Git for Windows
+====================================
Would it make sense for this to be checked in with LF instead of CRLF
line endings, so that clones use the user's chosen / platform native
line ending? The .gitattributes file could include
/CONTRIBUTING.md text
so that line ending conversion takes place even if the user hasn't
enabled core.autocrlf.
Oops! I turned off the CRLF munging in my repo because I had an issue
with a script somewhere, but forgot to turn it back on again. Thanks for
checking this.
[...]
+ The SDK uses a different credential manager, so you may still want to use
Visual Studio
+ or normal Git Bash for interacting with your remotes. Alternatively, use
SSH rather
+ than HTTPS and avoid credential manager problems.
Where can I read more about the problems in question?
I'll try to see if we can elaborate here. The Git for Windows client
ships with Git Credential Manager for Windows [1] but the SDK does not.
At the very least, credential interactions are not the same and you do
not have access to the credentials stored in Windows Credential Manager.
[1] https://github.com/Microsoft/Git-Credential-Manager-for-Windows
[...]
+Many new contributors ask: What should I start working on?
+
+One way to win big with the maintainer of an open-source project is to look at
the
+[issues page](https://github.com/git-for-windows/git/issues) and see if there
are any issues that
+you can fix quickly, or if anything catches your eye.
<shameless plug>You can also look at https://crbug.com/git for non
Windows-specific issues. And you can look at recent user questions
on the mailing list: https://public-inbox.org/git
[...]
+If you are adding new functionality, you may need to create low-level tests by
creating
+helper commands that test a very limited action. These commands are stored in
`t/helpers`.
+When adding a helper, be sure to add a line to `t/Makefile` and to the
`.gitignore` for the
+binary file you add. The Git community prefers functional tests using the full
`git`
+executable, so be sure the test helper is required.
Maybe s/low-level/unit/?
[...]
+Read [`t/README`](https://github.com/git/git/blob/master/t/README) for more
details.
Forgive my ignorance: does github flavored markdown allow relative
links? (I.e., could this say [`t/README`](t/README)?)
[...]
+You can also set certain environment variables to help test the performance on
different
+repositories or with more repetitions. The full list is available in
+[the `t/perf/README`
file](https://github.com/git/git/blob/master/t/perf/README),
Likewise.
[...]
+Test Your Changes on Linux
+--------------------------
+
+It can be important to work directly on the [core Git
codebase](https://github.com/git/git),
+such as a recent commit into the `master` or `next` branch that has not been
incorporated
+into Git for Windows. Also, it can help to run functional and performance
tests on your
+code in Linux before submitting patches to the Linux-focused mailing list.
I'm surprised at this advice. Does it actually come up? When I was
on Mac I never worried about this, nor when I was on Windows.
I'm personally happy to review patches that haven't been tested on
Linux, though it's of course even nicer if the patch author mentions
what platforms they've tested on.
Maybe this can be reframed to refer specifically to cases where you've
modified some Linux platform-specific code (e.g. to add a new feature
to run-command.c)?
I recently had a bug in my local copy of the commit-graph patch that was
only caught by our Mac OSX automated builds: I was passing the
edge-value for a parent into a lookup to get an octopus edge from the
graph, but I forgot to drop the most-significant bit. This cast the
"uint32_t" silently into an "int" but since we multiplied by 4 somehow
the Windows and Linux compilers turned this into a left-shift while Mac
did not and failed during my test.
Now this is an example of something that probably would have been caught
in review, but stuff gets through.
The Windows/Linux boundary is usually enough to catch the platform
differences, but they do catch things that you wouldn't think are
platform-specific.
[...]
+When preparing your patch, it is important to put yourself in the shoes of the
maintainer.
... and in the shoes of other users and developers working with Git down
the line who will interact with the patch later!
Actually, the maintainer is one of the least important audiences for a
commit message. But may 'the maintainer' is a stand-in for 'the
project' here?
Stand-in for "the community" yeah.
[...]
+* Make sure the commits are signed off using `git commit (-s|--signoff)`. This
means that you
+ testify to be allowed to contribute your changes, in particular that if you
did this on company
+ time, said company approved to releasing your work as Open Source under the
GNU Public License v2.
Can this either point to or quote the relevant legal text from
Documentation/SubmittingPatches? It feels dangerous (in the sense of,
potentially leading to misunderstandings and major future pain) to ask
people to sign off without them knowing exactly what that means.
+1 thanks.
The rest also looks nice. Thanks for working on this.
Sincerely,
Jonathan
Thanks for the feedback.
-Stolee
