diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/CodingGuidelines | 79 | ||||
| -rw-r--r-- | Documentation/Makefile | 1 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.47.0.txt | 133 | ||||
| -rw-r--r-- | Documentation/ReviewingGuidelines.txt | 25 | ||||
| -rw-r--r-- | Documentation/config/http.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-commit.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-ls-files.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-rebase.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-submodule.txt | 10 | ||||
| -rw-r--r-- | Documentation/githooks.txt | 15 | ||||
| -rw-r--r-- | Documentation/howto/maintain-git.txt | 158 | ||||
| -rw-r--r-- | Documentation/technical/platform-support.txt | 190 |
12 files changed, 550 insertions, 75 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 1d92b2da03..e4bd0abdcd 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -185,8 +185,8 @@ For shell scripts specifically (not exhaustive): - Even though "local" is not part of POSIX, we make heavy use of it in our test suite. We do not use it in scripted Porcelains, and - hopefully nobody starts using "local" before they are reimplemented - in C ;-) + hopefully nobody starts using "local" before all shells that matter + support it (notably, ksh from AT&T Research does not support it yet). - Some versions of shell do not understand "export variable=value", so we write "variable=value" and then "export variable" on two @@ -204,6 +204,33 @@ For shell scripts specifically (not exhaustive): local variable="$value" local variable="$(command args)" + - The common construct + + VAR=VAL command args + + to temporarily set and export environment variable VAR only while + "command args" is running is handy, but this triggers an + unspecified behaviour according to POSIX when used for a command + that is not an external command (like shell functions). Indeed, + dash 0.5.10.2-6 on Ubuntu 20.04, /bin/sh on FreeBSD 13, and AT&T + ksh all make a temporary assignment without exporting the variable, + in such a case. As it does not work portably across shells, do not + use this syntax for shell functions. A common workaround is to do + an explicit export in a subshell, like so: + + (incorrect) + VAR=VAL func args + + (correct) + ( + VAR=VAL && + export VAR && + func args + ) + + but be careful that the effect "func" makes to the variables in the + current shell will be lost across the subshell boundary. + - Use octal escape sequences (e.g. "\302\242"), not hexadecimal (e.g. "\xc2\xa2") in printf format strings, since hexadecimal escape sequences are not portable. @@ -214,6 +241,16 @@ For C programs: - We use tabs to indent, and interpret tabs as taking up to 8 spaces. + - Nested C preprocessor directives are indented after the hash by one + space per nesting level. + + #if FOO + # include <foo.h> + # if BAR + # include <bar.h> + # endif + #endif + - We try to keep to at most 80 characters per line. - As a Git developer we assume you have a reasonably modern compiler @@ -234,7 +271,7 @@ For C programs: . since around 2007 with 2b6854c863a, we have been using initializer elements which are not computable at load time. E.g.: - const char *args[] = {"constant", variable, NULL}; + const char *args[] = { "constant", variable, NULL }; . since early 2012 with e1327023ea, we have been using an enum definition whose last element is followed by a comma. This, like @@ -531,6 +568,42 @@ For C programs: use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + - The primary data structure that a subsystem 'S' deals with is called + `struct S`. Functions that operate on `struct S` are named + `S_<verb>()` and should generally receive a pointer to `struct S` as + first parameter. E.g. + + struct strbuf; + + void strbuf_add(struct strbuf *buf, ...); + + void strbuf_reset(struct strbuf *buf); + + is preferred over: + + struct strbuf; + + void add_string(struct strbuf *buf, ...); + + void reset_strbuf(struct strbuf *buf); + + - There are several common idiomatic names for functions performing + specific tasks on a structure `S`: + + - `S_init()` initializes a structure without allocating the + structure itself. + + - `S_release()` releases a structure's contents without freeing the + structure. + + - `S_clear()` is equivalent to `S_release()` followed by `S_init()` + such that the structure is directly usable after clearing it. When + `S_clear()` is provided, `S_init()` shall not allocate resources + that need to be released again. + + - `S_free()` releases a structure's contents and frees the + structure. + For Perl programs: - Most of the C guidelines above apply. diff --git a/Documentation/Makefile b/Documentation/Makefile index 1bd23fbeef..0f55baa252 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -118,6 +118,7 @@ TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/pack-heuristics TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone +TECH_DOCS += technical/platform-support TECH_DOCS += technical/racy-git TECH_DOCS += technical/reftable TECH_DOCS += technical/scalar diff --git a/Documentation/RelNotes/2.47.0.txt b/Documentation/RelNotes/2.47.0.txt new file mode 100644 index 0000000000..b948fa4db4 --- /dev/null +++ b/Documentation/RelNotes/2.47.0.txt @@ -0,0 +1,133 @@ +Git v2.47 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * Many Porcelain commands that internally use the merge machinery + were taught to consistently honor the diff.algorithm configuration. + + * A few descriptions in "git show-ref -h" have been clarified. + + * A 'P' command to "git add -p" that passes the patch hunk to the + pager has been added. + + * "git grep -W" omits blank lines that follow the found function at + the end of the file, just like it omits blank lines before the next + function. + + * The value of http.proxy can have "path" at the end for a socks + proxy that listens to a unix-domain socket, but we started to + discard it when we taught proxy auth code path to use the + credential helpers, which has been corrected. + + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * A build tweak knob has been simplified by not setting the value + that is already the default; another unused one has been removed. + + * A CI job that use clang-format to check coding style issues in new + code has been added. + + * The reviewing guidelines document now explicitly encourages people + to give positive reviews and how. + + * Test script linter has been updated to catch an attempt to use + one-shot export construct "VAR=VAL func" for shell functions (which + does not work for some shells) better. + + * Some project conventions have been added to CodingGuidelines. + + * In the refs subsystem, implicit reliance of the_repository has been + eliminated; the repository associated with the ref store object is + used instead. + + * Various tests in reftable library have been rewritten using the unit test + framework. + + * A test that fails on an unusually slow machine was found, and made + less likely to cause trouble by lengthening the expiry value it + uses. + + +Fixes since v2.46 +----------------- + + * "git add -p" by users with diff.suppressBlankEmpty set to true + failed to parse the patch that represents an unmodified empty line + with an empty line (not a line with a single space on it), which + has been corrected. + (merge 60cf761ed1 pw/add-patch-with-suppress-blank-empty later to maint). + + * "git checkout --ours" (no other arguments) complained that the + option is incompatible with branch switching, which is technically + correct, but found confusing by some users. It now says that the + user needs to give pathspec to specify what paths to checkout. + (merge d1e6c61272 jc/checkout-no-op-switch-errors later to maint). + + * It has been documented that we avoid "VAR=VAL shell_func" and why. + (merge 728a1962cd jc/doc-one-shot-export-with-shell-func later to maint). + + * "git rebase --help" referred to "offset" (the difference between + the location a change was taken from and the change gets replaced) + incorrectly and called it "fuzz", which has been corrected. + (merge 70058db385 jc/doc-rebase-fuzz-vs-offset-fix later to maint). + + * "git notes add -m '' --allow-empty" and friends that take prepared + data to create notes should not invoke an editor, but it started + doing so since Git 2.42, which has been corrected. + (merge 8b426c84f3 dd/notes-empty-no-edit-by-default later to maint). + + * An expensive operation to prepare tracing was done in re-encoding + code path even when the tracing was not requested, which has been + corrected. + (merge 63ad8dbf16 dh/encoding-trace-optim later to maint). + + * More leakfixes. + (merge f30bfafcd4 ps/leakfixes-part-3 later to maint). + + * The credential helper to talk to OSX keychain sometimes sent + garbage bytes after the username, which has been corrected. + (merge b201316835 jk/osxkeychain-username-is-nul-terminated later to maint). + + * A recent update broke "git ls-remote" used outside a repository, + which has been corrected. + (merge 9e89dcb66a ps/ls-remote-out-of-repo-fix later to maint). + + * The patch parser in 'git apply' has been a bit more lenient against + unexpected mode bits, like 100664, recorded on extended header lines. + (merge e95d515141 jk/apply-patch-mode-check-fix later to maint). + + * "git config --value=foo --fixed-value section.key newvalue" barfed + when the existing value in the configuration file used the + valueless true syntax, which has been corrected. + (merge 615d2de3b4 tb/config-fixed-value-with-valueless-true later to maint). + + * The patch parser in "git patch-id" has been tightened to avoid + getting confused by lines that look like a patch header in the log + message. + (merge a6e9429f72 jc/patch-id later to maint). + + * "git reflog expire" failed to honor annotated tags when computing + reachable commits. + (merge 5133ead528 jc/reflog-expire-lookup-commit-fix later to maint). + + * A flakey test and incorrect calls to strtoX() functions have been + fixed. + (merge ec60bb9fc4 kl/test-fixes later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 8db8786fc2 jt/doc-post-receive-hook-update later to maint). + (merge 1c473dd6af tn/doc-commit-fix later to maint). + (merge bb0498b1bb jc/how-to-maintain-updates later to maint). + (merge 6e71d6ac7c ks/unit-test-comment-typofix later to maint). + (merge 63ee933383 ps/p4-tests-updates later to maint). + (merge 7c7516b8db jc/jl-git-no-advice-fix later to maint). + (merge c3d034df16 jc/leakfix-hashfile later to maint). + (merge d98d9c77e5 jc/leakfix-mailmap later to maint). + (merge c199707496 jr/ls-files-expand-literal-doc later to maint). + (merge e2e373ba82 ss/packed-ref-store-leakfix later to maint). + (merge 0c4d5aa22d rs/use-decimal-width later to maint). + (merge 67be8c4de5 jc/document-use-of-local later to maint). diff --git a/Documentation/ReviewingGuidelines.txt b/Documentation/ReviewingGuidelines.txt index 515d470d23..6534643cff 100644 --- a/Documentation/ReviewingGuidelines.txt +++ b/Documentation/ReviewingGuidelines.txt @@ -72,12 +72,29 @@ guidance, and concrete tips for interacting with patches on the mailing list. could fix it. This not only helps the author to understand and fix the issue, it also deepens and improves your understanding of the topic. -- Reviews do not need to exclusively point out problems. Feel free to "think out +- Reviews do not need to exclusively point out problems. Positive + reviews indicate that it is not only the original author of the + patches who care about the issue the patches address, and are + highly encouraged. + +- Do not hesitate to give positive reviews on a series from your + work colleague. If your positive review is written well, it will + not make you look as if you two are representing corporate + interest on a series that is otherwise uninteresting to other + community members and shoving it down their throat. + +- Write a positive review in such a way that others can understand + why you support the goal, the approach, and the implementation the + patches took. Make sure to demonstrate that you did thoroughly read + the series and understood problem area well enough to be able to + say that the patches are written well. Feel free to "think out loud" in your review: describe how you read & understood a complex section of a patch, ask a question about something that confused you, point out something - you found exceptionally well-written, etc. In particular, uplifting feedback - goes a long way towards encouraging contributors to participate more actively - in the Git community. + you found exceptionally well-written, etc. + +- In particular, uplifting feedback goes a long way towards + encouraging contributors to participate more actively in the Git + community. ==== Performing your review - Provide your review comments per-patch in a plaintext "Reply-All" email to the diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index 162b33fc52..a14371b5c9 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -5,8 +5,8 @@ http.proxy:: proxy string with a user name but no password, in which case git will attempt to acquire one in the same way it does for other credentials. See linkgit:gitcredentials[7] for more information. The syntax thus is - '[protocol://][user[:password]@]proxyhost[:port]'. This can be overridden - on a per-remote basis; see remote.<name>.proxy + '[protocol://][user[:password]@]proxyhost[:port][/path]'. This can be + overridden on a per-remote basis; see remote.<name>.proxy + Any proxy, however configured, must be completely transparent and must not modify, transform, or buffer the request or response in any way. Proxies which diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 89ecfc63a8..c822113c11 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend] - [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)] + [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>] [-F <file> | -m <msg>] [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=<author>] [--date=<date>] [--cleanup=<mode>] [--[no-]status] diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index d08c7da8f4..58c529afbe 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -219,9 +219,9 @@ followed by the ("attr/<eolattr>"). --format=<format>:: A string that interpolates `%(fieldname)` from the result being shown. - It also interpolates `%%` to `%`, and `%xx` where `xx` are hex digits - interpolates to character with hex code `xx`; for example `%00` - interpolates to `\0` (NUL), `%09` to `\t` (TAB) and %0a to `\n` (LF). + It also interpolates `%%` to `%`, and `%xXX` where `XX` are hex digits + interpolates to character with hex code `XX`; for example `%x00` + interpolates to `\0` (NUL), `%x09` to `\t` (TAB) and %x0a to `\n` (LF). --format cannot be combined with `-s`, `-o`, `-k`, `-t`, `--resolve-undo` and `--eol`. \--:: diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 74df345f9e..b18cdbc023 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -737,7 +737,7 @@ The 'apply' backend works by creating a sequence of patches (by calling `format-patch` internally), and then applying the patches in sequence (calling `am` internally). Patches are composed of multiple hunks, each with line numbers, a context region, and the actual changes. The -line numbers have to be taken with some fuzz, since the other side +line numbers have to be taken with some offset, since the other side will likely have inserted or deleted lines earlier in the file. The context region is meant to help find how to adjust the line numbers in order to apply the changes to the right lines. However, if multiple diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index ca0347a37b..87d8e0f0c5 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -34,7 +34,7 @@ COMMANDS With no arguments, shows the status of existing submodules. Several subcommands are available to perform operations on the submodules. -add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]:: +add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]:: Add the given repository as a submodule at the given path to the changeset to be committed next to the current project: the current project is termed the "superproject". @@ -71,6 +71,9 @@ submodule repositories will be kept together in the same relative location, and only the superproject's URL needs to be provided. git-submodule will correctly locate the submodule using the relative URL in `.gitmodules`. ++ +If `--ref-format <format>` is specified, the ref storage format of newly +cloned submodules will be set accordingly. status [--cached] [--recursive] [--] [<path>...]:: Show the status of the submodules. This will print the SHA-1 of the @@ -136,7 +139,7 @@ If you really want to remove a submodule from the repository and commit that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal options. -update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>...]:: +update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>...]:: + -- Update the registered submodules to match what the superproject @@ -185,6 +188,9 @@ submodule with the `--init` option. If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. +If `--ref-format <format>` is specified, the ref storage format of newly +cloned submodules will be set accordingly. + If `--filter <filter-spec>` is specified, the given partial clone filter will be applied to the submodule. See linkgit:git-rev-list[1] for details on filter specifications. diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 06e997131b..0397dec64d 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -415,13 +415,13 @@ post-receive This hook is invoked by linkgit:git-receive-pack[1] when it reacts to `git push` and updates reference(s) in its repository. -It executes on the remote repository once after all the refs have -been updated. +The hook executes on the remote repository once after all the proposed +ref updates are processed and if at least one ref is updated as the +result. -This hook executes once for the receive operation. It takes no -arguments, but gets the same information as the -<<pre-receive,'pre-receive'>> -hook does on its standard input. +The hook takes no arguments. It receives one line on standard input for +each ref that is successfully updated following the same format as the +<<pre-receive,'pre-receive'>> hook. This hook does not affect the outcome of `git receive-pack`, as it is called after the real work is done. @@ -448,6 +448,9 @@ environment variables will not be set. If the client selects to use push options, but doesn't transmit any, the count variable will be set to zero, `GIT_PUSH_OPTION_COUNT=0`. +See the "post-receive" section in linkgit:git-receive-pack[1] for +additional details. + [[post-update]] post-update ~~~~~~~~~~~ diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt index 013014bbef..41f54050f8 100644 --- a/Documentation/howto/maintain-git.txt +++ b/Documentation/howto/maintain-git.txt @@ -37,22 +37,20 @@ The Policy The policy on Integration is informally mentioned in "A Note from the maintainer" message, which is periodically posted to -this mailing list after each feature release is made. +the mailing list after each feature release is made: - Feature releases are numbered as vX.Y.0 and are meant to contain bugfixes and enhancements in any area, including functionality, performance and usability, without regression. - - One release cycle for a feature release is expected to last for - eight to ten weeks. - - - Maintenance releases are numbered as vX.Y.Z and are meant + - Maintenance releases are numbered as vX.Y.Z (0 < Z) and are meant to contain only bugfixes for the corresponding vX.Y.0 feature release and earlier maintenance releases vX.Y.W (W < Z). - - 'master' branch is used to prepare for the next feature + - The 'master' branch is used to prepare for the next feature release. In other words, at some point, the tip of 'master' - branch is tagged with vX.Y.0. + branch is tagged as vX.(Y+1).0, when vX.Y.0 is the latest + feature release. - 'maint' branch is used to prepare for the next maintenance release. After the feature release vX.Y.0 is made, the tip @@ -63,11 +61,13 @@ this mailing list after each feature release is made. - 'next' branch is used to publish changes (both enhancements and fixes) that (1) have worthwhile goal, (2) are in a fairly good shape suitable for everyday use, (3) but have not yet - demonstrated to be regression free. New changes are tested - in 'next' before merged to 'master'. + demonstrated to be regression free. Reviews from contributors on + the mailing list help to make the determination. After a topic + is merged to 'next', it is tested for at least 7 calendar days + before getting merged to 'master'. - 'seen' branch is used to publish other proposed changes that do - not yet pass the criteria set for 'next'. + not yet pass the criteria set for 'next' (see above). - The tips of 'master' and 'maint' branches will not be rewound to allow people to build their own customization on top of them. @@ -86,6 +86,38 @@ this mailing list after each feature release is made. users are encouraged to test it so that regressions and bugs are found before new topics are merged to 'master'. + - When a problem is found in a topic in 'next', the topic is marked + not to be merged to 'master'. Follow-up patches are discussed on + the mailing list and applied to the topic after being reviewed and + then the topic is merged (again) to 'next'. After going through + the usual testing in 'next', the entire (fixed) topic is merged + to 'master'. + + - One release cycle for a feature release is expected to last for + eight to ten weeks. A few "release candidate" releases are + expected to be tagged about a week apart before the final + release, and a "preview" release is tagged about a week before + the first release candidate gets tagged. + + - After the preview release is tagged, topics that were well + reviewed may be merged to 'master' before spending the usual 7 + calendar days in 'next', with the expectation that any bugs in + them can be caught and fixed in the release candidates before + the final release. + + - After the first release candidate is tagged, the contributors are + strongly encouraged to focus on finding and fixing new regressions + introduced during the cycle, over addressing old bugs and any new + features. Topics stop getting merged down from 'next' to 'master', + and new topics stop getting merged to 'next'. Unless they are fixes + to new regressions in the cycle, that is. + + - Soon after a feature release is made, the tip of 'maint' gets + fast-forwarded to point at the release. Topics that have been + kept in 'next' are merged down to 'master' and a new development + cycle starts. + + Note that before v1.9.0 release, the version numbers used to be structured slightly differently. vX.Y.Z were feature releases while vX.Y.Z.W were maintenance releases for vX.Y.Z. @@ -179,12 +211,12 @@ by doing the following: The initial round is done with: $ git checkout ai/topic ;# or "git checkout -b ai/topic master" - $ git am -sc3 mailbox + $ git am -sc3 --whitespace=warn mailbox and replacing an existing topic with subsequent round is done with: $ git checkout master...ai/topic ;# try to reapply to the same base - $ git am -sc3 mailbox + $ git am -sc3 --whitespace=warn mailbox to prepare the new round on a detached HEAD, and then @@ -209,39 +241,59 @@ by doing the following: (trivial typofixes etc. are often squashed directly into the patches that need fixing, without being applied as a separate "SQUASH???" commit), so that they can be removed easily as needed. + The expectation is that the original author will make corrections + in a reroll. + - By now, new topic branches are created and existing topic + branches are updated. The integration branches 'next', 'jch', + and 'seen' need to be updated to contain them. - - Merge maint to master as needed: + - If there are topics that have been merged to 'master' and should + be merged to 'maint', merge them to 'maint', and update the + release notes to the next maintenance release. - $ git checkout master - $ git merge maint - $ make test + - Review the latest issue of "What's cooking" again. Are topics + that have been sufficiently long in 'next' ready to be merged to + 'master'? Are topics we saw earlier and are in 'seen' now got + positive reviews and are ready to be merged to 'next'? - - Merge master to next as needed: + - If there are topics that have been cooking in 'next' long enough + and should be merged to 'master', merge them to 'master', and + update the release notes to the next feature release. - $ git checkout next - $ git merge master - $ make test + - If there were patches directly made on 'maint', merge 'maint' to + 'master'; make sure that the result is what you want. - - Review the last issue of "What's cooking" again and see if topics - that are ready to be merged to 'next' are still in good shape - (e.g. has there any new issue identified on the list with the - series?) + $ git checkout master + $ git merge -m "Sync with 'maint'" --no-log maint + $ git log -p --first-parent ORIG_HEAD.. + $ make test - - Prepare 'jch' branch, which is used to represent somewhere - between 'master' and 'seen' and often is slightly ahead of 'next'. + - Prepare to update the 'jch' branch, which is used to represent + somewhere between 'master' and 'seen' and often is slightly ahead + of 'next', and the 'seen' branch, which is used to hold the rest. $ Meta/Reintegrate master..jch >Meta/redo-jch.sh The result is a script that lists topics to be merged in order to - rebuild 'seen' as the input to Meta/Reintegrate script. Remove - later topics that should not be in 'jch' yet. Add a line that - consists of '### match next' before the name of the first topic - in the output that should be in 'jch' but not in 'next' yet. + rebuild the current 'jch'. Do the same for 'seen'. + + - Review the Meta/redo-jch.sh and Meta/redo-seen.sh scripts. The + former should have a line '### match next'---the idea is that + merging the topics listed before the line on top of 'master' + should result in a tree identical to that of 'next'. - - Now we are ready to start merging topics to 'next'. For each - branch whose tip is not merged to 'next', one of three things can - happen: + - As newly created topics are usually merged near the tip of + 'seen', add them to the end of the Meta/redo-seen.sh script. + Among the topics that were in 'seen', there may be ones that + are not quite ready for 'next' but are getting there. Move + them from Meta/redo-seen.sh to the end of Meta/redo-jch.sh. + The expectation is that you'd use 'jch' as your daily driver + as the first guinea pig, so you should choose carefully. + + - Now we are ready to start rebuilding 'jch' and merging topics to + 'next'. For each branch whose tip is not merged to 'next', one + of three things can happen: - The commits are all next-worthy; merge the topic to next; - The new parts are of mixed quality, but earlier ones are @@ -252,10 +304,12 @@ by doing the following: If a topic that was already in 'next' gained a patch, the script would list it as "ai/topic~1". To include the new patch to the updated 'next', drop the "~1" part; to keep it excluded, do not - touch the line. If a topic that was not in 'next' should be - merged to 'next', add it at the end of the list. Then: + touch the line. + + If a topic that was not in 'next' should be merged to 'next', add + it before the '### match next' line. Then: - $ git checkout -B jch master + $ git checkout --detach master $ sh Meta/redo-jch.sh -c1 to rebuild the 'jch' branch from scratch. "-c1" tells the script @@ -267,26 +321,29 @@ by doing the following: reference to the variable under its old name), in which case prepare an appropriate merge-fix first (see appendix), and rebuild the 'jch' branch from scratch, starting at the tip of - 'master'. + 'master', this time without using "-c1" to merge all topics. - Then do the same to 'next' + Then do the same to 'next'. $ git checkout next $ sh Meta/redo-jch.sh -c1 -e The "-e" option allows the merge message that comes from the history of the topic and the comments in the "What's cooking" to - be edited. The resulting tree should match 'jch' as the same set - of topics are merged on 'master'; otherwise there is a mismerge. - Investigate why and do not proceed until the mismerge is found - and rectified. + be edited. The resulting tree should match 'jch^{/^### match next'}' + as the same set of topics are merged on 'master'; otherwise there + is a mismerge. Investigate why and do not proceed until the mismerge + is found and rectified. + + If 'master' was updated before you started redoing 'next', then - $ git diff jch next + $ git diff 'jch^{/^### match next}' next - Then build the rest of 'jch': + would show differences that went into 'master' (which 'jch' has, + but 'next' does not yet---often it is updates to the release + notes). Merge 'master' back to 'next' if that is the case. - $ git checkout jch - $ sh Meta/redo-jch.sh + $ git merge -m "Sync with 'master'" --no-log master When all is well, clean up the redo-jch.sh script with @@ -296,12 +353,7 @@ by doing the following: merged to 'master'. This may lose '### match next' marker; add it again to the appropriate place when it happens. - - Rebuild 'seen'. - - $ Meta/Reintegrate jch..seen >Meta/redo-seen.sh - - Edit the result by adding new topics that are not still in 'seen' - in the script. Then + - Rebuild 'seen' on top of 'jch'. $ git checkout -B seen jch $ sh Meta/redo-seen.sh @@ -312,7 +364,7 @@ by doing the following: Double check by running - $ git branch --no-merged seen + $ git branch --no-merged seen '??/*' to see there is no unexpected leftover topics. diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.txt new file mode 100644 index 0000000000..a227c363d7 --- /dev/null +++ b/Documentation/technical/platform-support.txt @@ -0,0 +1,190 @@ +Platform Support Policy +======================= + +Git has a history of providing broad "support" for exotic platforms and older +platforms, without an explicit commitment. Stakeholders of these platforms may +want a more predictable support commitment. This is only possible when platform +stakeholders supply Git developers with adequate tooling, so we can test for +compatibility or develop workarounds for platform-specific quirks on our own. +Various levels of platform-specific tooling will allow us to make more solid +commitments around Git's compatibility with that platform. + +Note that this document is about maintaining existing support for a platform +that has generally worked in the past; for adding support to a platform which +doesn't generally work with Git, the stakeholders for that platform are expected +to do the bulk of that work themselves. We will consider such patches if they +don't make life harder for other supported platforms or for Git contributors. +Some contributors may volunteer to help with the initial or continued support, +but that's not a given. Support work which is too intrusive or difficult for the +project to maintain may still not be accepted. + +Minimum Requirements +-------------------- + +The rest of this doc describes best practices for platforms to make themselves +easy to support. However, before considering support at all, platforms need to +meet the following minimum requirements: + +* Has C99 or C11 + +* Uses versions of dependencies which are generally accepted as stable and + supportable, e.g., in line with the version used by other long-term-support + distributions + +* Has active security support (taking security releases of dependencies, etc) + +These requirements are a starting point, and not sufficient on their own for the +Git community to be enthusiastic about supporting your platform. Maintainers of +platforms which do meet these requirements can follow the steps below to make it +more likely that Git updates will respect the platform's needs. + +Compatible by next release +-------------------------- + +To increase probability that compatibility issues introduced in a release +will be fixed in a later release: + +* You should send a bug report as soon as you notice the breakage on your + platform. The sooner you notice, the better; watching `seen` means you can + notice problems before they are considered "done with review"; whereas + watching `master` means the stable branch could break for your platform, but + you have a decent chance of avoiding a tagged release breaking you. See "The + Policy" in link:../howto/maintain-git.txt["How to maintain Git"] for an + overview of which branches are used in the Git project, and how. + +* The bug report should include information about what platform you are using. + +* You should also use linkgit:git-bisect[1] and determine which commit + introduced the breakage. + +* Please include any information you have about the nature of the breakage: is + it a memory alignment issue? Is an underlying library missing or broken for + your platform? Is there some quirk about your platform which means typical + practices (like malloc) behave strangely? + +* If possible, build Git from the exact same source both for your platform and + for a mainstream platform, to see if the problem you noticed appears only + on your platform. If the problem appears in both, then it's not a + compatibility issue, but we of course appreciate hearing about it in a bug + report anyway, to benefit users of every platform. If it appears only on your + platform, mention clearly that it is a compatibility issue in your report. + +* Once we begin to fix the issue, please work closely with the contributor + working on it to test the proposed fix against your platform. + +Example: NonStop +https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports +problems] when they're noticed. + +Compatible on `master` and releases +----------------------------------- + +To make sure all stable builds and regular releases work for your platform the +first time, help us avoid breaking `master` for your platform: + +* You should run regular tests against the `next` branch and + publish breakage reports to the mailing list immediately when they happen. + +** Ideally, these tests should run daily. They must run more often than + weekly, as topics generally spend at least 7 days in `next` before graduating + to `master`, and it takes time to put the brakes on a patch once it lands in + `next`. + +** You may want to ask to join the mailto:git-security@googlegroups.com[security + mailing list] in order to run tests against the fixes proposed there, too. + +* It may make sense to automate these; if you do, make sure they are not noisy + (you don't need to send a report when everything works, only when something + breaks; you don't need to send repeated reports for the same breakage night + after night). + +* Breakage reports should be actionable - include clear error messages that can + help developers who may not have access to test directly on your platform. + +* You should use git-bisect and determine which commit introduced the breakage; + if you can't do this with automation, you should do this yourself manually as + soon as you notice a breakage report was sent. + +* You should either: + +** Provide on-demand access to your platform to a trusted developer working to + fix the issue, so they can test their fix, OR + +** Work closely with the developer fixing the issue; the turnaround to check + that their proposed fix works for your platform should be fast enough that it + doesn't hinder the developer working on that fix. Slow testing turnarounds + may cause the fix to miss the next release, or the developer may lose + interest in working on the fix at all. + +Example: +https://lore.kernel.org/git/CAHd-oW6X4cwD_yLNFONPnXXUAFPxgDoccv2SOdpeLrqmHCJB4Q@mail.gmail.com/[AIX] +provides a build farm and runs tests against release candidates. + +Compatible on `next` +-------------------- + +To avoid reactive debugging and fixing when changes hit a release or stable, you +can aim to ensure `next` always works for your platform. (See "The Policy" in +link:../howto/maintain-git.txt["How to maintain Git"] for an overview of how +`next` is used in the Git project.) To do that: + +* You should add a runner for your platform to the GitHub Actions or GitLab CI + suite. This suite is run when any Git developer proposes a new patch, and + having a runner for your platform/configuration means every developer will + know if they break you, immediately. + +** If adding it to an existing CI suite is infeasible (due to architecture + constraints or for performance reasons), any other method which runs as + automatically and quickly as possible works, too. For example, a service + which snoops on the mailing list and automatically runs tests on new [PATCH] + emails, replying to the author with the results, would also be within the + spirit of this requirement. + +* If you rely on Git avoiding a specific pattern that doesn't work well with + your platform (like a certain malloc pattern), raise it on the mailing list. + We'll work case-by-case to look for a solution that doesn't unnecessarily + constrain other platforms to keep compatibility with yours. + +* If you rely on some configuration or behavior, add a test for it. Untested + behavior is subject to breakage at any time. + +** Clearly label these tests as necessary for platform compatibility. Add them + to an isolated compatibility-related test suite, like a new t* file or unit + test suite, so that they're easy to remove when compatibility is no longer + required. If the specific compatibility need is gated behind an issue with + another project, link to documentation of that issue (like a bug or email + thread) to make it easier to tell when that compatibility need goes away. + +** Include a comment with an expiration date for these tests no more than 1 year + from now. You can update the expiration date if your platform still needs + that assurance down the road, but we need to know you still care about that + compatibility case and are working to make it unnecessary. + +Example: We run our +https://git.kernel.org/pub/scm/git/git.git/tree/.github/workflows/main.yml[CI +suite] on Windows, Ubuntu, Mac, and others. + +Getting help writing platform support patches +--------------------------------------------- + +In general, when sending patches to fix platform support problems, follow +these guidelines to make sure the patch is reviewed with the appropriate level +of urgency: + +* Clearly state in the commit message that you are fixing a platform breakage, + and for which platform. + +* Use the CI and test suite to ensure that the fix for your platform doesn't + break other platforms. + +* If possible, add a test ensuring this regression doesn't happen again. If + it's not possible to add a test, explain why in the commit message. + +Platform Maintainers +-------------------- + +If you maintain a platform, or Git for that platform, and intend to work with +the Git project to ensure compatibility, please send a patch to add yourself to +this list. + +NonStop: Randall S. Becker <rsbecker@nexbridge.com> |