| 1 | To: git@vger.kernel.org |
| 2 | Subject: A note from the maintainer |
| 3 | |
| 4 | Welcome to the Git development community. |
| 5 | |
| 6 | This message is written by the maintainer and talks about how Git |
| 7 | project is managed, and how you can work with it. |
| 8 | |
| 9 | The current maintainer is Junio C Hamano <gitster@pobox.com>. Spam |
| 10 | filters learned that legitimate messages come to this address only |
| 11 | from a very few sender addresses that are known to be good, and all |
| 12 | other messages are likely to be spam unless they are also sent to the |
| 13 | mailing list at the same time (i.e. "Reply-all" to the list message |
| 14 | would reach the mailbox, but "Reply" will likely be thrown into the |
| 15 | spam folder), so please do not send a message to this address unless |
| 16 | it is also sent to the mailing list as well. |
| 17 | |
| 18 | |
| 19 | * Mailing list and the community |
| 20 | |
| 21 | The development is primarily done on the Git mailing list. Help |
| 22 | requests, feature proposals, bug reports and patches should be sent to |
| 23 | the list address <git@vger.kernel.org>. You don't have to be |
| 24 | subscribed to send messages. The convention on the list is to keep |
| 25 | everybody involved on Cc:, so it is unnecessary to say "Please Cc: me, |
| 26 | I am not subscribed". |
| 27 | |
| 28 | As an anti-spam measure, the mailing list software rejects messages |
| 29 | that are not text/plain and drops them on the floor. If you are a |
| 30 | GMail user, you'd want to make sure "Plain text mode" is checked. |
| 31 | |
| 32 | The mailing list, while welcoming non code contributions like bug |
| 33 | reports, mostly discusses updating contents of the source tree to the |
| 34 | (core) Git software, including documentation "git help" gives. |
| 35 | Non-code contributions may have places other than the mailing list |
| 36 | that are more preferrable. See the "other places" section near the |
| 37 | end. |
| 38 | |
| 39 | Before sending patches, please read Documentation/SubmittingPatches |
| 40 | and Documentation/CodingGuidelines to familiarize yourself with the |
| 41 | project convention. |
| 42 | |
| 43 | If you sent a patch and you did not hear any response from anybody for |
| 44 | several days, it does not necessarily mean that your patch was totally |
| 45 | uninteresting; it may merely mean that it was lost in the noise. |
| 46 | Please do not hesitate to send a reminder message in such a case. |
| 47 | Messages getting lost in the noise may be a sign that those who can |
| 48 | evaluate your patch don't have enough mental/time bandwidth to process |
| 49 | them right at the moment, and it often helps to wait until the list |
| 50 | traffic becomes calmer before sending such a reminder. |
| 51 | |
| 52 | The list archive is available at a few public sites: |
| 53 | |
| 54 | https://lore.kernel.org/git/ |
| 55 | https://marc.info/?l=git |
| 56 | https://www.spinics.net/lists/git/ |
| 57 | |
| 58 | For those who prefer to read it over NNTP: |
| 59 | |
| 60 | nntp://nntp.lore.kernel.org/org.kernel.vger.git |
| 61 | nntp://news.public-inbox.org/inbox.comp.version-control.git |
| 62 | |
| 63 | are available. |
| 64 | |
| 65 | When you point at a message in a mailing list archive, using its |
| 66 | message ID is often the most robust (if not very friendly) way to do |
| 67 | so, like this: |
| 68 | |
| 69 | https://lore.kernel.org/git/Pine.LNX.4.58.0504150753440.7211@ppc970.osdl.org |
| 70 | |
| 71 | Often these web interfaces accept the message ID with enclosing <> |
| 72 | stripped (like the above example to point at one of the most important |
| 73 | message in the Git mailing list). |
| 74 | |
| 75 | Some members of the development community can sometimes be found on |
| 76 | the #git and #git-devel IRC channels on Libera Chat. Their logs are |
| 77 | available at: |
| 78 | |
| 79 | https://colabti.org/ircloggy/git/last |
| 80 | https://colabti.org/ircloggy/git-devel/last |
| 81 | |
| 82 | There is a volunteer-run newsletter to serve our community ("Git Rev |
| 83 | News" https://git.github.io/rev_news/). |
| 84 | |
| 85 | Git is a member project of software freedom conservancy, a non-profit |
| 86 | organization (https://sfconservancy.org/). To reach a committee of |
| 87 | liaisons to the conservancy, contact them at <git@sfconservancy.org>. |
| 88 | |
| 89 | For our expectations on the behaviour of the community participants |
| 90 | towards each other, see CODE_OF_CONDUCT.md at the top level of the source |
| 91 | tree, or: |
| 92 | |
| 93 | https://github.com/git/git/blob/master/CODE_OF_CONDUCT.md |
| 94 | |
| 95 | |
| 96 | * Reporting bugs |
| 97 | |
| 98 | When you think git does not behave as you expect, please do not stop |
| 99 | your bug report with just "git does not work". "I used git in this |
| 100 | way, but it did not work" is not much better, neither is "I used git |
| 101 | in this way, and X happend, which is broken". It often is that git is |
| 102 | correct to cause X happen in such a case, and it is your expectation |
| 103 | that is broken. People would not know what other result Y you |
| 104 | expected to see instead of X, if you left it unsaid. |
| 105 | |
| 106 | Please remember to always state |
| 107 | |
| 108 | - what you wanted to achieve; |
| 109 | |
| 110 | - what you did (the version of git and the command sequence to reproduce |
| 111 | the behavior); |
| 112 | |
| 113 | - what you saw happen (X above); |
| 114 | |
| 115 | - what you expected to see (Y above); and |
| 116 | |
| 117 | - how the last two are different. |
| 118 | |
| 119 | See https://www.chiark.greenend.org.uk/~sgtatham/bugs.html for further |
| 120 | hints. Our `git bugreport` tool gives you a handy way you can use to |
| 121 | make sure you do not forget these points when filing a bug report. |
| 122 | |
| 123 | If you think you found a security-sensitive issue and want to disclose |
| 124 | it to us without announcing it to wider public, please contact us at |
| 125 | our security mailing list <git-security@googlegroups.com>. This is |
| 126 | a closed list that is limited to people who need to know early about |
| 127 | vulnerabilities, including: |
| 128 | |
| 129 | - people triaging and fixing reported vulnerabilities |
| 130 | - people operating major git hosting sites with many users |
| 131 | - people packaging and distributing git to large numbers of people |
| 132 | |
| 133 | where these issues are discussed without risk of the information |
| 134 | leaking out before we're ready to make public announcements. |
| 135 | |
| 136 | |
| 137 | * Repositories and documentation. |
| 138 | |
| 139 | My public git.git repositories are (mirrored) at: |
| 140 | |
| 141 | https://git.kernel.org/pub/scm/git/git.git/ |
| 142 | https://kernel.googlesource.com/pub/scm/git/git |
| 143 | https://repo.or.cz/alt-git.git/ |
| 144 | https://github.com/git/git/ |
| 145 | https://gitlab.com/git-scm/git/ |
| 146 | |
| 147 | This one shows not just the main integration branches, but also |
| 148 | individual topics broken out: |
| 149 | |
| 150 | https://github.com/gitster/git/ |
| 151 | |
| 152 | A few web interfaces are found at: |
| 153 | |
| 154 | https://git.kernel.org/pub/scm/git/git.git |
| 155 | https://kernel.googlesource.com/pub/scm/git/git |
| 156 | https://repo.or.cz/w/alt-git.git |
| 157 | |
| 158 | Preformatted documentation from the tip of the "master" branch can be |
| 159 | found in: |
| 160 | |
| 161 | https://git.kernel.org/pub/scm/git/git-{htmldocs,manpages}.git/ |
| 162 | https://repo.or.cz/git-{htmldocs,manpages}.git/ |
| 163 | https://github.com/gitster/git-{htmldocs,manpages}.git/ |
| 164 | |
| 165 | The manual pages formatted in HTML for the tip of "master" can be |
| 166 | viewed online at: |
| 167 | |
| 168 | https://git.github.io/htmldocs/git.html |
| 169 | |
| 170 | |
| 171 | * How various branches are used. |
| 172 | |
| 173 | There are four "integration" branches in git.git repository that track |
| 174 | the source tree of git: "master", "maint", "next", and "seen". They |
| 175 | however almost never get new commits made directly on them. Instead, |
| 176 | a branch is forked from either "master" or "maint" for each "topic", |
| 177 | whether it is a new feature or a fix for a bug, and holds a set of |
| 178 | commits that belong to the same theme. Such a "topic branch" is then |
| 179 | merged to these integration branches. |
| 180 | |
| 181 | The "master" branch is meant to contain what are very well tested and |
| 182 | ready to be used in a production setting. Every now and then, a |
| 183 | "feature release" is cut from the tip of this branch. They used to be |
| 184 | named with three dotted decimal digits (e.g., "1.8.5"), but we have |
| 185 | switched the versioning scheme and "feature releases" are named with |
| 186 | ttwo-dotted decimal digits (e.g. "2.53"), whose tag ends with ".0" |
| 187 | (e.g., "v2.53.0"). |
| 188 | |
| 189 | The last such release was Git 2.53, made on Feb 2nd, 2026. We aim to |
| 190 | make sure that the tip of the "master" branch is always more stable |
| 191 | than any of the released versions. |
| 192 | |
| 193 | Whenever a feature release is made, "maint" branch is forked off from |
| 194 | "master" at that point. Obvious and safe fixes for bugs in the latest |
| 195 | feature release are merged to this branch and maintenance releases are |
| 196 | cut from it. Usually the topic branches that contain these fixes are |
| 197 | merged to the "master" branch first, before getting merged to the |
| 198 | "maint" branch, to reduce the chance of last-minute issues, but |
| 199 | things like embargoed security fixes may first appear in the "maint" |
| 200 | and merged up to "master" at the same time. The maintenance releases |
| 201 | used to be named with four dotted decimal, named after the feature |
| 202 | release they are updates to (e.g., "1.8.5.1" was the first maintenance |
| 203 | release for "1.8.5" feature release). These days, maintenance releases |
| 204 | are named by incrementing the last digit of three-dotted decimal name |
| 205 | (e.g., "2.47.1" was the second maintenance release for the "2.47" series). |
| 206 | |
| 207 | New features almost never go to the "maint" branch, although changes |
| 208 | to help Git developers themselves, including CI updates, are often |
| 209 | merged down even if they are not bugfixes at all. The "maint" branch |
| 210 | is merged up into the "master" branch, primarily to propagate the |
| 211 | description in the release notes forward. |
| 212 | |
| 213 | When you send a series of patches, after review discussions on the |
| 214 | mailing list, a separate topic branch is forked from the tip of |
| 215 | "master" (or somewhere older, especially when the topic is about |
| 216 | fixing an earlier bug) and your patches are applied on that topic |
| 217 | branch, and kept out of "master" while people test it out. The |
| 218 | quality of topic branches are judged primarily by the mailing list |
| 219 | discussions. |
| 220 | |
| 221 | Topic branches that are in good shape are merged to the "next" branch. |
| 222 | The "next" branch is where new and exciting things take place. In |
| 223 | general, the "next" branch always contains the tip of "master". It |
| 224 | might not be quite rock-solid, but is expected to work more or less |
| 225 | without major breakage. A topic that is in "next" is expected to be |
| 226 | polished to perfection before it is merged to "master". Please help |
| 227 | this process by building & using the "next" branch for your daily |
| 228 | work, and reporting any new bugs you find to the mailing list, before |
| 229 | the breakage is merged down to the "master". This process depends on |
| 230 | your participation, as the way you use Git may be unique from others, |
| 231 | and a new bug may only manifest itself when used in the way you use |
| 232 | Git, not noticed by others. |
| 233 | |
| 234 | The "seen" branch bundles the remaining topic branches that the |
| 235 | maintainer happens to have seen to remind the maintainer that the |
| 236 | topics in them might become interesting when they are polished. A |
| 237 | topic in "seen" can and does get discarded before it gets merged to |
| 238 | "next" if its idea does not pan out, just like a topic can wither on |
| 239 | the list without anybody supporting it. Please do not read anything |
| 240 | more than "the maintainer has seen it and found it potentially |
| 241 | interesting" into a topic being in "seen". |
| 242 | |
| 243 | The contributors can use the "seen" branch to anticipate what topics |
| 244 | by others may cause conflicts with their own work, and find people who |
| 245 | are working on these topics to talk to before the potential conflicts |
| 246 | get out of control. It would be a good idea to fork your work from |
| 247 | maint or master and to (1) test it by itself, (2) test a temporary |
| 248 | merge of it to "next" and (3) test a temporary merge to it to "seen", |
| 249 | before sending it to the list (or asking GitGitGadget to send it to |
| 250 | the list). |
| 251 | |
| 252 | You can run "git log --oneline --first-parent master..seen" to see |
| 253 | what topics are currently in flight. The output of the above command |
| 254 | talks about a "jch" branch, which is an early part of the "seen" branch; |
| 255 | that branch contains all topics that are in "next" and a bit more (but |
| 256 | not all of "seen") and is used by the maintainer for his daily work. |
| 257 | |
| 258 | The two branches "master" and "maint" are never rewound, and "next" |
| 259 | usually will not be either. After a feature release is made from |
| 260 | "master", however, "next" will be rebuilt from the tip of "master" |
| 261 | using the topics that didn't make the cut in the feature release. |
| 262 | Some topics that used to be in "next" during the previous cycle may |
| 263 | get ejected from "next" when this happens. |
| 264 | |
| 265 | A natural consequence of how "next" and "seen" bundles topics together |
| 266 | is that until a topic is merged to "next", updates to it is expected |
| 267 | by replacing the patch(es) in the topic with an improved version, and |
| 268 | once a topic is merged to "next", updates to it needs to come as |
| 269 | incremental patches, pointing out what was wrong in the previous |
| 270 | patches and how the problem was corrected. The idea is that if many |
| 271 | reviewers thought it has seen enough eyeballs and is good enough for |
| 272 | "next", yet we later find that there was something we all missed, that |
| 273 | is worth a separate explanation, e.g., "The primary motivation behind |
| 274 | the series is still good, but for such and such reasons we missed this |
| 275 | case we are fixing.", hence we prefer follow-up incremental patches. |
| 276 | |
| 277 | Note that being in "next" is not a guarantee to appear in the next |
| 278 | release, nor even in any future release. There were cases that topics |
| 279 | needed reverting a few commits in them before graduating to "master", |
| 280 | or a topic that already was in "next" was reverted from "next" because |
| 281 | fatal flaws were found in it after it was merged to "next". The same |
| 282 | can be said to "master"---there were cases that we needed to revert a |
| 283 | topic from it because a regression was found after it was merged to |
| 284 | "master", instead of while it was still in "next". To prevent it from |
| 285 | happening, those who care about the quality of the next release, those |
| 286 | who want to ensure that the next release will not break their |
| 287 | workflow, are strongly encouraged to build and try out "next" in their |
| 288 | daily work and report problems. |
| 289 | |
| 290 | |
| 291 | * Other people's trees. |
| 292 | |
| 293 | Documentation/SubmittingPatches outlines to whom your proposed changes |
| 294 | should be sent. As described in contrib/README, I would delegate fixes |
| 295 | and enhancements in contrib/ area to the primary contributors of them. |
| 296 | |
| 297 | Although the following are included in git.git repository, they have their |
| 298 | own authoritative repository and maintainers: |
| 299 | |
| 300 | - git-gui/ comes from git-gui project, maintained by Johannes Sixt: |
| 301 | |
| 302 | https://github.com/j6t/git-gui |
| 303 | |
| 304 | - gitk-git/ comes from gitk project, maintained by Johannes Sixt: |
| 305 | |
| 306 | https://github.com/j6t/gitk |
| 307 | |
| 308 | - po/ comes from the localization coordinator, Jiang Xin: |
| 309 | |
| 310 | https://github.com/git-l10n/git-po/ |
| 311 | |
| 312 | When sending proposed updates and fixes to these parts of the system, |
| 313 | please base your patches on these trees, not git.git (the former two |
| 314 | even have different directory structures). |
| 315 | |
| 316 | |
| 317 | * Other places. |
| 318 | |
| 319 | As the Git ecosystem has grown larger over the years, there are |
| 320 | documentation sites and third-party tools that have been created and |
| 321 | maintained by friendly third-parties. Reporting issues with them to |
| 322 | the main mailing list is still welcomed by the list participants, but |
| 323 | most likely you will be asked to contact these third-parties directly. |
| 324 | |
| 325 | - git-scm website (https://www.git-scm.com/) is maintained directly |
| 326 | on its GitHub repository and its issues are managed there. |
| 327 | |
| 328 | https://github.com/git/git-scm.com/issues |
| 329 | https://github.com/git/git-scm.com/?tab=readme-ov-file#contributing |
| 330 | |
| 331 | - Git for Windows (https://gitforwindows.org/) is a project that |
| 332 | packages (core) Git software with some other goodies for the |
| 333 | Windows platform. They manage their own issues list and their |
| 334 | changes are managed directly on GitHub via pull requests, focused |
| 335 | primarily on Windows specific issues and their additions (like |
| 336 | Windows installer). |
| 337 | |
| 338 | https://github.com/git-for-windows/git/wiki/How-to-participate |
| 339 | https://github.com/git-for-windows/git/issues |
| 340 | |
| 341 | - The online edition of ProGit Book hosted at git-scm.com/book/ is |
| 342 | managed by the Pro Git book folks, and they maintain their work and |
| 343 | issues at their GitHub repository. |
| 344 | |
| 345 | https://github.com/progit/progit2/issues |
| 346 | https://github.com/progit/progit2/blob/main/CONTRIBUTING.md |