git/Documentation
Linus Arver 0a02ca2383 SubmittingPatches: simplify guidance for choosing a starting point
Background: The guidance to "base your work on the oldest branch that
your change is relevant to" was added in d0c26f0f56 (SubmittingPatches:
Add new section about what to base work on, 2010-04-19). That commit
also added the bullet points which describe the scenarios where one
would use one of the following named branches: "maint", "master",
"next", and "seen" ("pu" in the original as that was the name of this
branch before it was renamed, per 828197de8f (docs: adjust for the
recent rename of `pu` to `seen`, 2020-06-25)). The guidance was probably
taken from existing similar language introduced in the "Merge upwards"
section of gitworkflows in f948dd8992 (Documentation: add manpage about
workflows, 2008-10-19).

Summary: This change simplifies the guidance by pointing users to just
"maint" or "master". But it also gives an explanation of why that is
preferred and what is meant by preferring "older" branches (which might
be confusing to some because "old" here is meant in relative terms
between these named branches, not in terms of the age of the branches
themselves). We also add an example to illustrate why it would be a bad
idea to use "next" as a starting point, which may not be so obvious to
new contributors.

Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Linus Arver <linusa@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2023-07-14 10:31:43 -07:00
..
RelNotes Git 2.41-rc2 2023-05-25 05:55:19 +09:00
config Merge branch 'cg/doc-http-lowspeed-limit' 2023-05-20 05:35:56 +09:00
howto new-command.txt: update reference to builtin docs 2023-02-06 14:07:33 -08:00
includes
…
mergetools
…
technical Merge branch 'ds/bundle-uri-5' 2023-02-15 17:11:52 -08:00
.gitattributes
…
.gitignore doc: remove manpage-base-url workaround 2023-04-05 14:18:53 -07:00
CodingGuidelines treewide: ensure one of the appropriate headers is sourced first 2023-02-23 17:25:28 -08:00
Makefile Merge branch 'fc/doc-stop-using-manversion' 2023-04-21 15:35:04 -07:00
MyFirstContribution.txt Merge branch 'la/mfc-markup-fix' 2023-04-17 18:05:12 -07:00
MyFirstObjectWalk.txt
…
ReviewingGuidelines.txt
…
SubmittingPatches SubmittingPatches: simplify guidance for choosing a starting point 2023-07-14 10:31:43 -07:00
ToolsForGit.txt
…
asciidoc.conf doc: asciidoc: remove custom header macro 2023-04-05 21:37:45 -07:00
asciidoctor-extensions.rb
…
blame-options.txt blame: use different author name for fake commit generated by --contents 2023-04-24 15:16:31 -07:00
build-docdep.perl Documentation/build-docdep.perl: generate sorted output 2022-10-21 11:39:38 -07:00
cat-texi.perl
…
cmd-list.perl
…
config.txt Merge branch 'ds/bundle-uri-3' 2022-10-30 21:04:44 -04:00
date-formats.txt
…
diff-format.txt
…
diff-generate-patch.txt docs: link generating patch sections 2023-01-13 12:55:14 -08:00
diff-options.txt diff: add --default-prefix option 2023-03-09 08:32:21 -08:00
doc-diff doc-diff: drop SOURCE_DATE_EPOCH override 2023-05-05 14:28:03 -07:00
docbook-xsl.css
…
docbook.xsl
…
everyday.txto
…
fetch-options.txt fetch: introduce machine-parseable "porcelain" output format 2023-05-10 10:35:25 -07:00
fix-texi.perl
…
fsck-msgids.txt fsck: document the new `gitattributes` message IDs 2023-01-16 12:03:14 -08:00
git-add.txt docs & comments: replace mentions of "git-add--interactive.perl" 2023-02-06 15:03:34 -08:00
git-am.txt am: refer to format-patch in the documentation 2023-03-21 13:18:45 -07:00
git-annotate.txt
…
git-apply.txt Documentation: render dash correctly 2023-01-23 09:40:14 -08:00
git-archimport.txt
…
git-archive.txt archive: add --mtime 2023-02-18 09:29:13 -08:00
git-bisect-lk2009.txt git-bisect-lk2009: update nist report link 2023-01-13 11:58:51 -08:00
git-bisect.txt
…
git-blame.txt blame: allow --contents to work with non-HEAD commit 2023-03-24 12:05:22 -07:00
git-branch.txt branch, for-each-ref, tag: add option to omit empty lines 2023-04-13 08:07:45 -07:00
git-bugreport.txt
…
git-bundle.txt Merge branch 'jk/bundle-use-dash-for-stdfiles' 2023-03-19 15:03:12 -07:00
git-cat-file.txt git-cat-file.txt: fix list continuations rendering literally 2023-01-18 08:24:39 -08:00
git-check-attr.txt attr: add flag `--source` to work with tree-ish 2023-01-14 08:49:55 -08:00
git-check-ignore.txt
…
git-check-mailmap.txt
…
git-check-ref-format.txt
…
git-checkout-index.txt
…
git-checkout.txt doc: git-checkout: reorganize examples 2023-04-18 15:47:13 -07:00
git-cherry-pick.txt git-cherry-pick.txt: do not use 'ORIG_HEAD' in example 2023-01-13 09:55:45 -08:00
git-cherry.txt
…
git-citool.txt
…
git-clean.txt Merge branch 'ab/doc-synopsis-and-cmd-usage' 2022-10-28 11:26:54 -07:00
git-clone.txt clone: error specifically with --local and symlinked objects 2023-04-11 08:46:09 -07:00
git-column.txt
…
git-commit-graph.txt Merge branch 'ab/doc-synopsis-and-cmd-usage' 2022-10-28 11:26:54 -07:00
git-commit-tree.txt
…
git-commit.txt
…
git-config.txt
…
git-count-objects.txt
…
git-credential-cache--daemon.txt
…
git-credential-cache.txt Documentation: clarify that cache forgets credentials if the system restarts 2023-01-29 09:21:07 -08:00
git-credential-store.txt
…
git-credential.txt Merge branch 'mh/credential-oauth-refresh-token' 2023-05-10 10:23:29 -07:00
git-cvsexportcommit.txt
…
git-cvsimport.txt
…
git-cvsserver.txt
…
git-daemon.txt
…
git-describe.txt
…
git-diagnose.txt
…
git-diff-files.txt
…
git-diff-index.txt
…
git-diff-tree.txt
…
git-diff.txt Merge branch 'rs/diff-caret-bang-with-parents' 2022-10-25 17:11:43 -07:00
git-difftool.txt mergetool: new config guiDefault supports auto-toggling gui by DISPLAY 2023-04-05 21:03:29 -07:00
git-fast-export.txt
…
git-fast-import.txt
…
git-fetch-pack.txt
…
git-fetch.txt fetch: introduce machine-parseable "porcelain" output format 2023-05-10 10:35:25 -07:00
git-filter-branch.txt
…
git-fmt-merge-msg.txt
…
git-for-each-ref.txt Merge branch 'ow/ref-filter-omit-empty' 2023-04-21 15:35:05 -07:00
git-for-each-repo.txt
…
git-format-patch.txt Merge branch 'ah/format-patch-thread-doc' 2023-04-21 15:35:05 -07:00
git-fsck-objects.txt
…
git-fsck.txt fsck: document msg-id 2022-10-25 15:44:18 -07:00
git-fsmonitor--daemon.txt
…
git-gc.txt builtin/gc.c: make `gc.cruftPacks` enabled by default 2023-04-18 14:56:48 -07:00
git-get-tar-commit-id.txt
…
git-grep.txt
…
git-gui.txt
…
git-hash-object.txt
…
git-help.txt
…
git-hook.txt hook: support a --to-stdin=<path> option 2023-02-08 12:50:03 -08:00
git-http-backend.txt
…
git-http-fetch.txt
…
git-http-push.txt
…
git-imap-send.txt
…
git-index-pack.txt
…
git-init-db.txt
…
git-init.txt
…
git-instaweb.txt
…
git-interpret-trailers.txt doc: interpret-trailers: fix example 2023-05-01 13:26:42 -07:00
git-log.txt
…
git-ls-files.txt ls-files: guide folks to --exclude-standard over other --exclude* options 2023-01-13 11:55:17 -08:00
git-ls-remote.txt doc/ls-remote: clarify pattern format 2023-02-10 21:57:51 -08:00
git-ls-tree.txt
…
git-mailinfo.txt
…
git-mailsplit.txt
…
git-maintenance.txt maintenance: add option to register in a specific config 2022-11-14 22:39:25 -05:00
git-merge-base.txt
…
git-merge-file.txt
…
git-merge-index.txt
…
git-merge-one-file.txt
…
git-merge-tree.txt Merge branch 'as/doc-markup-fix' 2023-03-19 15:03:11 -07:00
git-merge.txt git-merge.txt: mention 'ORIG_HEAD' in the Description 2023-01-13 09:55:46 -08:00
git-mergetool--lib.txt
…
git-mergetool.txt mergetool: new config guiDefault supports auto-toggling gui by DISPLAY 2023-04-05 21:03:29 -07:00
git-mktag.txt
…
git-mktree.txt
…
git-multi-pack-index.txt
…
git-mv.txt
…
git-name-rev.txt name-rev: make --stdin hidden 2023-05-06 14:32:20 -07:00
git-notes.txt
…
git-p4.txt
…
git-pack-objects.txt
…
git-pack-redundant.txt pack-redundant: document deprecation 2023-03-30 07:50:43 -07:00
git-pack-refs.txt
…
git-patch-id.txt builtin: patch-id: add --verbatim as a command mode 2022-10-24 15:44:20 -07:00
git-prune-packed.txt
…
git-prune.txt
…
git-pull.txt
…
git-push.txt push: introduce '--branches' option 2023-05-06 14:36:43 -07:00
git-quiltimport.txt
…
git-range-diff.txt
…
git-read-tree.txt Documentation: render dash correctly 2023-01-23 09:40:14 -08:00
git-rebase.txt rebase: add a config option for --rebase-merges 2023-03-27 09:32:49 -07:00
git-receive-pack.txt
…
git-reflog.txt
…
git-remote-ext.txt
…
git-remote-fd.txt
…
git-remote-helpers.txto
…
git-remote.txt
…
git-repack.txt builtin/repack.c: implement `--expire-to` for storing pruned objects 2022-10-24 13:39:42 -07:00
git-replace.txt
…
git-request-pull.txt
…
git-rerere.txt
…
git-reset.txt git-reset.txt: mention 'ORIG_HEAD' in the Description 2023-01-13 09:55:45 -08:00
git-restore.txt
…
git-rev-list.txt
…
git-rev-parse.txt fetch: support hideRefs to speed up connectivity checks 2023-02-27 09:27:03 -08:00
git-revert.txt Merge branch 'ab/doc-synopsis-and-cmd-usage' 2022-11-29 10:41:06 +09:00
git-rm.txt
…
git-send-email.txt Merge branch 'mc/send-email-header-cmd' 2023-05-15 13:59:03 -07:00
git-send-pack.txt
…
git-sh-i18n--envsubst.txt
…
git-sh-i18n.txt
…
git-sh-setup.txt
…
git-shell.txt
…
git-shortlog.txt shortlog: support arbitrary commit format `--group`s 2022-10-24 14:48:05 -07:00
git-show-branch.txt Merge branch 'ab/doc-synopsis-and-cmd-usage' 2022-10-28 11:26:54 -07:00
git-show-index.txt
…
git-show-ref.txt
…
git-show.txt
…
git-sparse-checkout.txt builtin/sparse-checkout: add check-rules command 2023-03-27 10:51:12 -07:00
git-stage.txt
…
git-stash.txt Merge branch 'ab/doc-synopsis-and-cmd-usage' 2022-10-28 11:26:54 -07:00
git-status.txt status: modernize git-status "slow untracked files" advice 2022-12-01 15:27:41 +09:00
git-stripspace.txt
…
git-submodule.txt
…
git-svn.txt
…
git-switch.txt
…
git-symbolic-ref.txt
…
git-tag.txt branch, for-each-ref, tag: add option to omit empty lines 2023-04-13 08:07:45 -07:00
git-tools.txt
…
git-unpack-file.txt
…
git-unpack-objects.txt
…
git-update-index.txt
…
git-update-ref.txt
…
git-update-server-info.txt
…
git-upload-archive.txt
…
git-upload-pack.txt
…
git-var.txt var: add GIT_SEQUENCE_EDITOR variable 2022-12-18 11:48:26 +09:00
git-verify-commit.txt
…
git-verify-pack.txt
…
git-verify-tag.txt
…
git-version.txt
…
git-web--browse.txt
…
git-whatchanged.txt
…
git-worktree.txt
…
git-write-tree.txt
…
git.txt Merge branch 'jc/attr-source-tree' 2023-05-17 10:11:41 -07:00
gitattributes.txt docs: rewrite the documentation of the text and eol attributes 2023-05-03 09:02:11 -07:00
gitcli.txt
…
gitcore-tutorial.txt
…
gitcredentials.txt credential: new attribute password_expiry_utc 2023-02-22 15:18:58 -08:00
gitcvs-migration.txt
…
gitdiffcore.txt
…
giteveryday.txt
…
gitfaq.txt
…
gitformat-bundle.txt
…
gitformat-chunk.txt
…
gitformat-commit-graph.txt doc: use "commit-graph" hyphenation consistently 2022-10-30 19:58:40 -04:00
gitformat-index.txt docs: document zero bits in index "mode" 2023-02-01 08:49:23 -08:00
gitformat-pack.txt builtin/gc.c: make `gc.cruftPacks` enabled by default 2023-04-18 14:56:48 -07:00
gitformat-signature.txt Merge branch 'gm/signature-format-doc' 2023-03-06 21:51:56 -08:00
gitglossary.txt
…
githooks.txt Merge branch 'ms/send-email-feed-header-to-validate-hook' 2023-05-10 10:23:28 -07:00
gitignore.txt docs: clarify git rm --cached function in gitignore note 2023-05-03 14:59:34 -07:00
gitk.txt
…
gitmailmap.txt
…
gitmodules.txt
…
gitnamespaces.txt
…
gitprotocol-capabilities.txt
…
gitprotocol-common.txt
…
gitprotocol-http.txt
…
gitprotocol-pack.txt
…
gitprotocol-v2.txt *: fix typos which duplicate a word 2023-01-08 10:28:34 +09:00
gitremote-helpers.txt
…
gitrepository-layout.txt
…
gitrevisions.txt
…
gitsubmodules.txt
…
gittutorial-2.txt
…
gittutorial.txt gittutorial: wrap literal examples in backticks 2023-04-20 14:34:08 -07:00
gitweb.conf.txt
…
gitweb.txt
…
gitworkflows.txt
…
glossary-content.txt glossary: add reachability bitmap description 2022-10-30 19:58:46 -04:00
howto-index.sh
…
i18n.txt
…
install-doc-quick.sh
…
install-webdoc.sh
…
line-range-format.txt
…
line-range-options.txt
…
lint-fsck-msgids.perl Documentation: add lint-fsck-msgids 2022-10-25 15:44:19 -07:00
lint-gitlink.perl
…
lint-man-end-blurb.perl
…
lint-man-section-order.perl
…
manpage-bold-literal.xsl
…
manpage-normal.xsl Merge branch 'fc/doc-man-lift-title-length-limit' 2023-05-10 10:23:29 -07:00
manpage.xsl
…
merge-options.txt
…
merge-strategies.txt
…
object-format-disclaimer.txt
…
pretty-formats.txt doc: pretty-formats note wide char limitations, and add tests 2023-01-19 14:35:15 -08:00
pretty-options.txt
…
pull-fetch-param.txt
…
ref-reachability-filters.txt
…
rerere-options.txt
…
rev-list-description.txt
…
rev-list-options.txt Merge branch 'jk/document-rev-list-object-name' 2023-04-04 14:28:29 -07:00
revisions.txt revisions.txt: be explicit about commands writing 'ORIG_HEAD' 2023-01-13 09:55:46 -08:00
scalar.txt
…
sequencer.txt
…
signoff-option.txt
…
texi.xsl
…
trace2-target-values.txt
…
transfer-data-leaks.txt
…
urls-remotes.txt Documentation: clarify multiple pushurls vs urls 2023-02-07 11:02:27 -08:00
urls.txt
…
user-manual.conf
…
user-manual.txt
…