| Submitting Patches |
| ================== |
| |
| == Guidelines |
| |
| Here are some guidelines for contributing back to this |
| project. There is also a link:MyFirstContribution.html[step-by-step tutorial] |
| available which covers many of these same guidelines. |
| |
| [[choose-starting-point]] |
| === Choose a starting point. |
| |
| As a preliminary step, you must first choose a starting point for your |
| work. Typically this means choosing a branch, although technically |
| speaking it is actually a particular commit (typically the HEAD, or tip, |
| of the branch). |
| |
| There are several important branches to be aware of. Namely, there are |
| four integration branches as discussed in linkgit:gitworkflows[7]: |
| |
| * maint |
| * master |
| * next |
| * seen |
| |
| The branches lower on the list are typically descendants of the ones |
| that come before it. For example, `maint` is an "older" branch than |
| `master` because `master` usually has patches (commits) on top of |
| `maint`. |
| |
| There are also "topic" branches, which contain work from other |
| contributors. Topic branches are created by the Git maintainer (in |
| their fork) to organize the current set of incoming contributions on |
| the mailing list, and are itemized in the regular "What's cooking in |
| git.git" announcements. To find the tip of a topic branch, run `git log |
| --first-parent master..seen` and look for the merge commit. The second |
| parent of this commit is the tip of the topic branch. |
| |
| There is one guiding principle for choosing the right starting point: in |
| general, always base your work on the oldest integration branch that |
| your change is relevant to (see "Merge upwards" in |
| linkgit:gitworkflows[7]). What this principle means is that for the |
| vast majority of cases, the starting point for new work should be the |
| latest HEAD commit of `maint` or `master` based on the following cases: |
| |
| * If you are fixing bugs in the released version, use `maint` as the |
| starting point (which may mean you have to fix things without using |
| new API features on the cutting edge that recently appeared in |
| `master` but were not available in the released version). |
| |
| * Otherwise (such as if you are adding new features) use `master`. |
| |
| |
| NOTE: In exceptional cases, a bug that was introduced in an old |
| version may have to be fixed for users of releases that are much older |
| than the recent releases. `git describe --contains X` may describe |
| `X` as `v2.30.0-rc2-gXXXXXX` for the commit `X` that introduced the |
| bug, and the bug may be so high-impact that we may need to issue a new |
| maintenance release for Git 2.30.x series, when "Git 2.41.0" is the |
| current release. In such a case, you may want to use the tip of the |
| maintenance branch for the 2.30.x series, which may be available in the |
| `maint-2.30` branch in https://github.com/gitster/git[the maintainer's |
| "broken out" repo]. |
| |
| This also means that `next` or `seen` are inappropriate starting points |
| for your work, if you want your work to have a realistic chance of |
| graduating to `master`. They are simply not designed to be used as a |
| base for new work; they are only there to make sure that topics in |
| flight work well together. This is why both `next` and `seen` are |
| frequently re-integrated with incoming patches on the mailing list and |
| force-pushed to replace previous versions of themselves. A topic that is |
| literally built on top of `next` cannot be merged to `master` without |
| dragging in all the other topics in `next`, some of which may not be |
| ready. |
| |
| For example, if you are making tree-wide changes, while somebody else is |
| also making their own tree-wide changes, your work may have severe |
| overlap with the other person's work. This situation may tempt you to |
| use `next` as your starting point (because it would have the other |
| person's work included in it), but doing so would mean you'll not only |
| depend on the other person's work, but all the other random things from |
| other contributors that are already integrated into `next`. And as soon |
| as `next` is updated with a new version, all of your work will need to |
| be rebased anyway in order for them to be cleanly applied by the |
| maintainer. |
| |
| Under truly exceptional circumstances where you absolutely must depend |
| on a select few topic branches that are already in `next` but not in |
| `master`, you may want to create your own custom base-branch by forking |
| `master` and merging the required topic branches into it. You could then |
| work on top of this base-branch. But keep in mind that this base-branch |
| would only be known privately to you. So when you are ready to send |
| your patches to the list, be sure to communicate how you created it in |
| your cover letter. This critical piece of information would allow |
| others to recreate your base-branch on their end in order for them to |
| try out your work. |
| |
| Finally, note that some parts of the system have dedicated maintainers |
| with their own separate source code repositories (see the section |
| "Subsystems" below). |
| |
| [[separate-commits]] |
| === Make separate commits for logically separate changes. |
| |
| Unless your patch is really trivial, you should not be sending |
| out a patch that was generated between your working tree and |
| your commit head. Instead, always make a commit with complete |
| commit message and generate a series of patches from your |
| repository. It is a good discipline. |
| |
| Give an explanation for the change(s) that is detailed enough so |
| that people can judge if it is good thing to do, without reading |
| the actual patch text to determine how well the code does what |
| the explanation promises to do. |
| |
| If your description starts to get too long, that's a sign that you |
| probably need to split up your commit to finer grained pieces. |
| That being said, patches which plainly describe the things that |
| help reviewers check the patch, and future maintainers understand |
| the code, are the most beautiful patches. Descriptions that summarize |
| the point in the subject well, and describe the motivation for the |
| change, the approach taken by the change, and if relevant how this |
| differs substantially from the prior version, are all good things |
| to have. |
| |
| Make sure that you have tests for the bug you are fixing. See |
| `t/README` for guidance. |
| |
| [[tests]] |
| When adding a new feature, make sure that you have new tests to show |
| the feature triggers the new behavior when it should, and to show the |
| feature does not trigger when it shouldn't. After any code change, |
| make sure that the entire test suite passes. When fixing a bug, make |
| sure you have new tests that break if somebody else breaks what you |
| fixed by accident to avoid regression. Also, try merging your work to |
| 'next' and 'seen' and make sure the tests still pass; topics by others |
| that are still in flight may have unexpected interactions with what |
| you are trying to do in your topic. |
| |
| Pushing to a fork of https://github.com/git/git will use their CI |
| integration to test your changes on Linux, Mac and Windows. See the |
| <<GHCI,GitHub CI>> section for details. |
| |
| Do not forget to update the documentation to describe the updated |
| behavior and make sure that the resulting documentation set formats |
| well (try the Documentation/doc-diff script). |
| |
| We currently have a liberal mixture of US and UK English norms for |
| spelling and grammar, which is somewhat unfortunate. A huge patch that |
| touches the files all over the place only to correct the inconsistency |
| is not welcome, though. Potential clashes with other changes that can |
| result from such a patch are not worth it. We prefer to gradually |
| reconcile the inconsistencies in favor of US English, with small and |
| easily digestible patches, as a side effect of doing some other real |
| work in the vicinity (e.g. rewriting a paragraph for clarity, while |
| turning en_UK spelling to en_US). Obvious typographical fixes are much |
| more welcomed ("teh -> "the"), preferably submitted as independent |
| patches separate from other documentation changes. |
| |
| [[whitespace-check]] |
| Oh, another thing. We are picky about whitespaces. Make sure your |
| changes do not trigger errors with the sample pre-commit hook shipped |
| in `templates/hooks--pre-commit`. To help ensure this does not happen, |
| run `git diff --check` on your changes before you commit. |
| |
| [[describe-changes]] |
| === Describe your changes well. |
| |
| The log message that explains your changes is just as important as the |
| changes themselves. Your code may be clearly written with in-code |
| comment to sufficiently explain how it works with the surrounding |
| code, but those who need to fix or enhance your code in the future |
| will need to know _why_ your code does what it does, for a few |
| reasons: |
| |
| . Your code may be doing something differently from what you wanted it |
| to do. Writing down what you actually wanted to achieve will help |
| them fix your code and make it do what it should have been doing |
| (also, you often discover your own bugs yourself, while writing the |
| log message to summarize the thought behind it). |
| |
| . Your code may be doing things that were only necessary for your |
| immediate needs (e.g. "do X to directories" without implementing or |
| even designing what is to be done on files). Writing down why you |
| excluded what the code does not do will help guide future developers. |
| Writing down "we do X to directories, because directories have |
| characteristic Y" would help them infer "oh, files also have the same |
| characteristic Y, so perhaps doing X to them would also make sense?". |
| Saying "we don't do the same X to files, because ..." will help them |
| decide if the reasoning is sound (in which case they do not waste |
| time extending your code to cover files), or reason differently (in |
| which case, they can explain why they extend your code to cover |
| files, too). |
| |
| The goal of your log message is to convey the _why_ behind your |
| change to help future developers. |
| |
| The first line of the commit message should be a short description (50 |
| characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), |
| and should skip the full stop. It is also conventional in most cases to |
| prefix the first line with "area: " where the area is a filename or |
| identifier for the general area of the code being modified, e.g. |
| |
| * doc: clarify distinction between sign-off and pgp-signing |
| * githooks.txt: improve the intro section |
| |
| If in doubt which identifier to use, run `git log --no-merges` on the |
| files you are modifying to see the current conventions. |
| |
| [[summary-section]] |
| The title sentence after the "area:" prefix omits the full stop at the |
| end, and its first word is not capitalized (the omission |
| of capitalization applies only to the word after the "area:" |
| prefix of the title) unless there is a reason to |
| capitalize it other than because it is the first word in the sentence. |
| E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt: |
| improve...", not "githooks.txt: Improve...". But "refs: HEAD is also |
| treated as a ref" is correct, as we spell `HEAD` in all caps even when |
| it appears in the middle of a sentence. |
| |
| [[meaningful-message]] |
| The body should provide a meaningful commit message, which: |
| |
| . explains the problem the change tries to solve, i.e. what is wrong |
| with the current code without the change. |
| |
| . justifies the way the change solves the problem, i.e. why the |
| result with the change is better. |
| |
| . alternate solutions considered but discarded, if any. |
| |
| [[present-tense]] |
| The problem statement that describes the status quo is written in the |
| present tense. Write "The code does X when it is given input Y", |
| instead of "The code used to do Y when given input X". You do not |
| have to say "Currently"---the status quo in the problem statement is |
| about the code _without_ your change, by project convention. |
| |
| [[imperative-mood]] |
| Describe your changes in imperative mood, e.g. "make xyzzy do frotz" |
| instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy |
| to do frotz", as if you are giving orders to the codebase to change |
| its behavior. Try to make sure your explanation can be understood |
| without external resources. Instead of giving a URL to a mailing list |
| archive, summarize the relevant points of the discussion. |
| |
| [[commit-reference]] |
| |
| There are a few reasons why you may want to refer to another commit in |
| the "more stable" part of the history (i.e. on branches like `maint`, |
| `master`, and `next`): |
| |
| . A commit that introduced the root cause of a bug you are fixing. |
| |
| . A commit that introduced a feature that you are enhancing. |
| |
| . A commit that conflicts with your work when you made a trial merge |
| of your work into `next` and `seen` for testing. |
| |
| When you reference a commit on a more stable branch (like `master`, |
| `maint` and `next`), use the format "abbreviated hash (subject, |
| date)", like this: |
| |
| .... |
| Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) |
| noticed that ... |
| .... |
| |
| The "Copy commit reference" command of gitk can be used to obtain this |
| format (with the subject enclosed in a pair of double-quotes), or this |
| invocation of `git show`: |
| |
| .... |
| git show -s --pretty=reference <commit> |
| .... |
| |
| or, on an older version of Git without support for --pretty=reference: |
| |
| .... |
| git show -s --date=short --pretty='format:%h (%s, %ad)' <commit> |
| .... |
| |
| [[sign-off]] |
| === Certify your work by adding your `Signed-off-by` trailer |
| |
| To improve tracking of who did what, we ask you to certify that you |
| wrote the patch or have the right to pass it on under the same license |
| as ours, by "signing off" your patch. Without sign-off, we cannot |
| accept your patches. |
| |
| If (and only if) you certify the below D-C-O: |
| |
| [[dco]] |
| .Developer's Certificate of Origin 1.1 |
| ____ |
| By making a contribution to this project, I certify that: |
| |
| a. The contribution was created in whole or in part by me and I |
| have the right to submit it under the open source license |
| indicated in the file; or |
| |
| b. The contribution is based upon previous work that, to the best |
| of my knowledge, is covered under an appropriate open source |
| license and I have the right under that license to submit that |
| work with modifications, whether created in whole or in part |
| by me, under the same open source license (unless I am |
| permitted to submit under a different license), as indicated |
| in the file; or |
| |
| c. The contribution was provided directly to me by some other |
| person who certified (a), (b) or (c) and I have not modified |
| it. |
| |
| d. I understand and agree that this project and the contribution |
| are public and that a record of the contribution (including all |
| personal information I submit with it, including my sign-off) is |
| maintained indefinitely and may be redistributed consistent with |
| this project or the open source license(s) involved. |
| ____ |
| |
| you add a "Signed-off-by" trailer to your commit, that looks like |
| this: |
| |
| .... |
| Signed-off-by: Random J Developer <random@developer.example.org> |
| .... |
| |
| This line can be added by Git if you run the git-commit command with |
| the -s option. |
| |
| Notice that you can place your own `Signed-off-by` trailer when |
| forwarding somebody else's patch with the above rules for |
| D-C-O. Indeed you are encouraged to do so. Do not forget to |
| place an in-body "From: " line at the beginning to properly attribute |
| the change to its true author (see (2) above). |
| |
| This procedure originally came from the Linux kernel project, so our |
| rule is quite similar to theirs, but what exactly it means to sign-off |
| your patch differs from project to project, so it may be different |
| from that of the project you are accustomed to. |
| |
| [[real-name]] |
| Also notice that a real name is used in the `Signed-off-by` trailer. Please |
| don't hide your real name. |
| |
| [[commit-trailers]] |
| If you like, you can put extra tags at the end: |
| |
| . `Reported-by:` is used to credit someone who found the bug that |
| the patch attempts to fix. |
| . `Acked-by:` says that the person who is more familiar with the area |
| the patch attempts to modify liked the patch. |
| . `Reviewed-by:`, unlike the other tags, can only be offered by the |
| reviewers themselves when they are completely satisfied with the |
| patch after a detailed analysis. |
| . `Tested-by:` is used to indicate that the person applied the patch |
| and found it to have the desired effect. |
| . `Co-authored-by:` is used to indicate that people exchanged drafts |
| of a patch before submitting it. |
| . `Helped-by:` is used to credit someone who suggested ideas for |
| changes without providing the precise changes in patch form. |
| . `Mentored-by:` is used to credit someone with helping develop a |
| patch as part of a mentorship program (e.g., GSoC or Outreachy). |
| . `Suggested-by:` is used to credit someone with suggesting the idea |
| for a patch. |
| |
| While you can also create your own trailer if the situation warrants it, we |
| encourage you to instead use one of the common trailers in this project |
| highlighted above. |
| |
| Only capitalize the very first letter of tags, i.e. favor |
| "Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By". |
| |
| [[git-tools]] |
| === Generate your patch using Git tools out of your commits. |
| |
| Git based diff tools generate unidiff which is the preferred format. |
| |
| You do not have to be afraid to use `-M` option to `git diff` or |
| `git format-patch`, if your patch involves file renames. The |
| receiving end can handle them just fine. |
| |
| [[review-patch]] |
| Please make sure your patch does not add commented out debugging code, |
| or include any extra files which do not relate to what your patch |
| is trying to achieve. Make sure to review |
| your patch after generating it, to ensure accuracy. Before |
| sending out, please make sure it cleanly applies to the starting point you |
| have chosen in the "Choose a starting point" section. |
| |
| NOTE: From the perspective of those reviewing your patch, the `master` |
| branch is the default expected starting point. So if you have chosen a |
| different starting point, please communicate this choice in your cover |
| letter. |
| |
| |
| [[send-patches]] |
| === Sending your patches. |
| |
| :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com] |
| |
| Before sending any patches, please note that patches that may be |
| security relevant should be submitted privately to the Git Security |
| mailing list{security-ml}, instead of the public mailing list. |
| |
| Learn to use format-patch and send-email if possible. These commands |
| are optimized for the workflow of sending patches, avoiding many ways |
| your existing e-mail client (often optimized for "multipart/*" MIME |
| type e-mails) might render your patches unusable. |
| |
| People on the Git mailing list need to be able to read and |
| comment on the changes you are submitting. It is important for |
| a developer to be able to "quote" your changes, using standard |
| e-mail tools, so that they may comment on specific portions of |
| your code. For this reason, each patch should be submitted |
| "inline" in a separate message. |
| |
| All subsequent versions of a patch series and other related patches should be |
| grouped into their own e-mail thread to help readers find all parts of the |
| series. To that end, send them as replies to either an additional "cover |
| letter" message (see below), the first patch, or the respective preceding patch. |
| Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on |
| how to submit updated versions of a patch series. |
| |
| If your log message (including your name on the |
| `Signed-off-by` trailer) is not writable in ASCII, make sure that |
| you send off a message in the correct encoding. |
| |
| WARNING: Be wary of your MUAs word-wrap |
| corrupting your patch. Do not cut-n-paste your patch; you can |
| lose tabs that way if you are not careful. |
| |
| It is a common convention to prefix your subject line with |
| [PATCH]. This lets people easily distinguish patches from other |
| e-mail discussions. Use of markers in addition to PATCH within |
| the brackets to describe the nature of the patch is also |
| encouraged. E.g. [RFC PATCH] (where RFC stands for "request for |
| comments") is often used to indicate a patch needs further |
| discussion before being accepted, [PATCH v2], [PATCH v3] etc. |
| are often seen when you are sending an update to what you have |
| previously sent. |
| |
| The `git format-patch` command follows the best current practice to |
| format the body of an e-mail message. At the beginning of the |
| patch should come your commit message, ending with the |
| `Signed-off-by` trailers, and a line that consists of three dashes, |
| followed by the diffstat information and the patch itself. If |
| you are forwarding a patch from somebody else, optionally, at |
| the beginning of the e-mail message just before the commit |
| message starts, you can put a "From: " line to name that person. |
| To change the default "[PATCH]" in the subject to "[<text>]", use |
| `git format-patch --subject-prefix=<text>`. As a shortcut, you |
| can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or |
| `-v <n>` instead of `--subject-prefix="PATCH v<n>"`. |
| |
| You often want to add additional explanation about the patch, |
| other than the commit message itself. Place such "cover letter" |
| material between the three-dash line and the diffstat. For |
| patches requiring multiple iterations of review and discussion, |
| an explanation of changes between each iteration can be kept in |
| Git-notes and inserted automatically following the three-dash |
| line via `git format-patch --notes`. |
| |
| [[the-topic-summary]] |
| *This is EXPERIMENTAL*. |
| |
| When sending a topic, you can propose a one-paragraph summary that |
| should appear in the "What's cooking" report when it is picked up to |
| explain the topic. If you choose to do so, please write a 2-5 line |
| paragraph that will fit well in our release notes (see many bulleted |
| entries in the Documentation/RelNotes/* files for examples), and make |
| it the first paragraph of the cover letter. For a single-patch |
| series, use the space between the three-dash line and the diffstat, as |
| described earlier. |
| |
| [[attachment]] |
| Do not attach the patch as a MIME attachment, compressed or not. |
| Do not let your e-mail client send quoted-printable. Do not let |
| your e-mail client send format=flowed which would destroy |
| whitespaces in your patches. Many |
| popular e-mail applications will not always transmit a MIME |
| attachment as plain text, making it impossible to comment on |
| your code. A MIME attachment also takes a bit more time to |
| process. This does not decrease the likelihood of your |
| MIME-attached change being accepted, but it makes it more likely |
| that it will be postponed. |
| |
| Exception: If your mailer is mangling patches then someone may ask |
| you to re-send them using MIME, that is OK. |
| |
| [[pgp-signature]] |
| Do not PGP sign your patch. Most likely, your maintainer or other people on the |
| list would not have your PGP key and would not bother obtaining it anyway. |
| Your patch is not judged by who you are; a good patch from an unknown origin |
| has a far better chance of being accepted than a patch from a known, respected |
| origin that is done poorly or does incorrect things. |
| |
| If you really really really really want to do a PGP signed |
| patch, format it as "multipart/signed", not a text/plain message |
| that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is |
| not a text/plain, it's something else. |
| |
| :security-ml-ref: footnoteref:[security-ml] |
| |
| As mentioned at the beginning of the section, patches that may be |
| security relevant should not be submitted to the public mailing list |
| mentioned below, but should instead be sent privately to the Git |
| Security mailing list{security-ml-ref}. |
| |
| Send your patch with "To:" set to the mailing list, with "cc:" listing |
| people who are involved in the area you are touching (the `git |
| contacts` command in `contrib/contacts/` can help to |
| identify them), to solicit comments and reviews. Also, when you made |
| trial merges of your topic to `next` and `seen`, you may have noticed |
| work by others conflicting with your changes. There is a good possibility |
| that these people may know the area you are touching well. |
| |
| :current-maintainer: footnote:[The current maintainer: gitster@pobox.com] |
| :git-ml: footnote:[The mailing list: git@vger.kernel.org] |
| |
| After the list reached a consensus that it is a good idea to apply the |
| patch, re-send it with "To:" set to the maintainer{current-maintainer} |
| and "cc:" the list{git-ml} for inclusion. This is especially relevant |
| when the maintainer did not heavily participate in the discussion and |
| instead left the review to trusted others. |
| |
| Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and |
| `Tested-by:` lines as necessary to credit people who helped your |
| patch, and "cc:" them when sending such a final version for inclusion. |
| |
| == Subsystems with dedicated maintainers |
| |
| Some parts of the system have dedicated maintainers with their own |
| repositories. |
| |
| - `git-gui/` comes from git-gui project, maintained by Johannes Sixt: |
| |
| https://github.com/j6t/git-gui |
| |
| - `gitk-git/` comes from Paul Mackerras's gitk project: |
| |
| git://git.ozlabs.org/~paulus/gitk |
| |
| Those who are interested in improving gitk can volunteer to help Paul |
| maintain it, cf. <YntxL/fTplFm8lr6@cleo>. |
| |
| - `po/` comes from the localization coordinator, Jiang Xin: |
| |
| https://github.com/git-l10n/git-po/ |
| |
| Patches to these parts should be based on their trees. |
| |
| - The "Git documentation translations" project, led by Jean-Noël |
| Avila, translates our documentation pages. Their work products are |
| maintained separately from this project, not as part of our tree: |
| |
| https://github.com/jnavila/git-manpages-l10n/ |
| |
| |
| [[patch-flow]] |
| == An ideal patch flow |
| |
| Here is an ideal patch flow for this project the current maintainer |
| suggests to the contributors: |
| |
| . You come up with an itch. You code it up. |
| |
| . Send it to the list and cc people who may need to know about |
| the change. |
| + |
| The people who may need to know are the ones whose code you |
| are butchering. These people happen to be the ones who are |
| most likely to be knowledgeable enough to help you, but |
| they have no obligation to help you (i.e. you ask for help, |
| don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would |
| help you find out who they are. |
| |
| . You get comments and suggestions for improvements. You may |
| even get them in an "on top of your change" patch form. |
| |
| . Polish, refine, and re-send to the list and the people who |
| spend their time to improve your patch. Go back to step (2). |
| |
| . The list forms consensus that the last round of your patch is |
| good. Send it to the maintainer and cc the list. |
| |
| . A topic branch is created with the patch and is merged to `next`, |
| and cooked further and eventually graduates to `master`. |
| |
| In any time between the (2)-(3) cycle, the maintainer may pick it up |
| from the list and queue it to `seen`, in order to make it easier for |
| people to play with it without having to pick up and apply the patch to |
| their trees themselves. |
| |
| [[patch-status]] |
| == Know the status of your patch after submission |
| |
| * You can use Git itself to find out when your patch is merged in |
| master. `git pull --rebase` will automatically skip already-applied |
| patches, and will let you know. This works only if you rebase on top |
| of the branch in which your patch has been merged (i.e. it will not |
| tell you if your patch is merged in `seen` if you rebase on top of |
| master). |
| |
| * Read the Git mailing list, the maintainer regularly posts messages |
| entitled "What's cooking in git.git" giving |
| the status of various proposed changes. |
| |
| == GitHub CI[[GHCI]] |
| |
| With an account at GitHub, you can use GitHub CI to test your changes |
| on Linux, Mac and Windows. See |
| https://github.com/git/git/actions/workflows/main.yml for examples of |
| recent CI runs. |
| |
| Follow these steps for the initial setup: |
| |
| . Fork https://github.com/git/git to your GitHub account. |
| You can find detailed instructions how to fork here: |
| https://help.github.com/articles/fork-a-repo/ |
| |
| After the initial setup, CI will run whenever you push new changes |
| to your fork of Git on GitHub. You can monitor the test state of all your |
| branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml` |
| |
| If a branch does not pass all test cases then it will be marked with a |
| red +x+, instead of a green check. In that case, you can click on the |
| failing job and navigate to "ci/run-build-and-tests.sh" and/or |
| "ci/print-test-failures.sh". You can also download "Artifacts" which |
| are zip archives containing tarred (or zipped) archives with test data |
| relevant for debugging. |
| |
| Then fix the problem and push your fix to your GitHub fork. This will |
| trigger a new CI build to ensure all tests pass. |
| |
| [[mua]] |
| == MUA specific hints |
| |
| Some of the patches I receive or pick up from the list share common |
| patterns of breakage. Please make sure your MUA is set up |
| properly not to corrupt whitespaces. |
| |
| See the DISCUSSION section of linkgit:git-format-patch[1] for hints on |
| checking your patch by mailing it to yourself and applying with |
| linkgit:git-am[1]. |
| |
| While you are at it, check the resulting commit log message from |
| a trial run of applying the patch. If what is in the resulting |
| commit is not exactly what you would want to see, it is very |
| likely that your maintainer would end up hand editing the log |
| message when he applies your patch. Things like "Hi, this is my |
| first patch.\n", if you really want to put in the patch e-mail, |
| should come after the three-dash line that signals the end of the |
| commit message. |
| |
| |
| === Pine |
| |
| (Johannes Schindelin) |
| |
| .... |
| I don't know how many people still use pine, but for those poor |
| souls it may be good to mention that the quell-flowed-text is |
| needed for recent versions. |
| |
| ... the "no-strip-whitespace-before-send" option, too. AFAIK it |
| was introduced in 4.60. |
| .... |
| |
| (Linus Torvalds) |
| |
| .... |
| And 4.58 needs at least this. |
| |
| diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) |
| Author: Linus Torvalds <torvalds@g5.osdl.org> |
| Date: Mon Aug 15 17:23:51 2005 -0700 |
| |
| Fix pine whitespace-corruption bug |
| |
| There's no excuse for unconditionally removing whitespace from |
| the pico buffers on close. |
| |
| diff --git a/pico/pico.c b/pico/pico.c |
| --- a/pico/pico.c |
| +++ b/pico/pico.c |
| @@ -219,7 +219,9 @@ PICO *pm; |
| switch(pico_all_done){ /* prepare for/handle final events */ |
| case COMP_EXIT : /* already confirmed */ |
| packheader(); |
| +#if 0 |
| stripwhitespace(); |
| +#endif |
| c |= COMP_EXIT; |
| break; |
| .... |
| |
| (Daniel Barkalow) |
| |
| .... |
| > A patch to SubmittingPatches, MUA specific help section for |
| > users of Pine 4.63 would be very much appreciated. |
| |
| Ah, it looks like a recent version changed the default behavior to do the |
| right thing, and inverted the sense of the configuration option. (Either |
| that or Gentoo did it.) So you need to set the |
| "no-strip-whitespace-before-send" option, unless the option you have is |
| "strip-whitespace-before-send", in which case you should avoid checking |
| it. |
| .... |
| |
| === Thunderbird, KMail, GMail |
| |
| See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1]. |
| |
| === Gnus |
| |
| "|" in the `*Summary*` buffer can be used to pipe the current |
| message to an external program, and this is a handy way to drive |
| `git am`. However, if the message is MIME encoded, what is |
| piped into the program is the representation you see in your |
| `*Article*` buffer after unwrapping MIME. This is often not what |
| you would want for two reasons. It tends to screw up non-ASCII |
| characters (most notably in people's names), and also |
| whitespaces (fatal in patches). Running "C-u g" to display the |
| message in raw form before using "|" to run the pipe can work |
| this problem around. |