kumquat-buildroot/docs/manual
Yann E. MORIN 970cb26ec2 docs/manual: using a branch name as FOO_VERSION does not work
For various reasons, we've always suggested users to avoid using a
branch as version string for their packages, because it does not work
as a they would expect:

  - it is not reproducible, because the branch may change between two
    builds that are done at different times;

  - it does not even follow the branch, as Buildroot anyway generates
    a local tarball, which it will reuse on subsequent builds.
    Furthermore, since we fetch and not pull, any existing local branch
    is not updated.

Yet, until recently, using a branch name would just work (with the
above limitations): the git tree was cloned, the branch checked out,
and the tarball created.

But with the advent of the git caching, using a branch name does not
work anymore. Indeed, we now do a git-fetch, and that does not create
a local master branch. So we can't check out master, because it does
not exist locally. And for other branches, as noticed above, the local
branch does not get udpated to the remote one.

Furthermore, the local branches are only created by chance, again as a
side-effect of trying to fetch the "special refs".

So, we can't say that we reliably support the use of a branch name.

Update the manual to state that using a branch does not work. Remove
the 'stable' example, as it looked like the name of a stable branch;
instead, replace it with a version string that ressemble a tag.

Fix the layout of the manual by making the version examples an actual
bulleted list.

Note: the above is only entirely true for git. For Mercurial, CVS and
subversion, the status may be mixed, but nonetheless, using branches is
still a bad idea, if at least because it is not reproducible, and
because Buildroot does not even follow the branch. So, we do not
differentiate between the various SCMs, and just flatly state that using
a branch name is not supported.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Cc: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
Cc: Maxime Hadjinlian <maxime.hadjinlian@gmail.com>
Cc: Peter Korsgaard <peter@korsgaard.com>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2018-05-11 23:03:21 +02:00
..
adding-board-support.txt
adding-packages-asciidoc.txt docs/manual: document the br2-external NAME 2016-10-16 13:01:02 +02:00
adding-packages-autotools.txt
adding-packages-cargo.txt docs/manual: use SPDX short identifier for license 2018-04-05 21:06:45 +02:00
adding-packages-cmake.txt
adding-packages-conclusion.txt
adding-packages-directory.txt toolchain: merge toolchain-common.in to Config.in 2018-04-01 08:45:54 +02:00
adding-packages-generic.txt docs/manual: using a branch name as FOO_VERSION does not work 2018-05-11 23:03:21 +02:00
adding-packages-gettext.txt docs/manual: update gettext details 2017-07-05 01:37:38 +02:00
adding-packages-golang.txt package/pkg-golang: use 'build' instead of 'install' 2018-04-01 16:36:28 +02:00
adding-packages-hooks.txt manual: patches are not applied for SITE_METHOD = local 2017-07-09 17:25:48 +02:00
adding-packages-kconfig.txt docs/manual: update pkg-kconfig doc about <pkg>_KCONFIG_DOTCONFIG 2016-09-17 14:46:04 +02:00
adding-packages-kernel-module.txt docs/manual: refer to SPDX License List 2017-04-01 15:11:18 +02:00
adding-packages-linux-kernel-spec-infra.txt package/linux-tools: change method for including linux-tool sub-makefiles 2017-07-19 21:16:38 +02:00
adding-packages-luarocks.txt luarocks-package: lowercase the upstream name for LuaRocks 2017-03-05 22:01:39 +01:00
adding-packages-meson.txt docs/manual: use SPDX short identifier for license 2018-04-05 21:06:45 +02:00
adding-packages-perl.txt docs/manual: refer to SPDX License List 2017-04-01 15:11:18 +02:00
adding-packages-python.txt manual: update old references to support/scripts 2017-07-01 19:43:46 +02:00
adding-packages-rebar.txt
adding-packages-tips.txt docs/manual: add check-package to "Tips and tricks" 2018-04-02 00:42:59 +02:00
adding-packages-virtual.txt manual: get rid of the lists of packages 2016-09-19 19:32:59 +02:00
adding-packages-waf.txt doc/manual: document the new waf-package infra variables 2016-12-11 18:03:59 +01:00
adding-packages.txt docs/manual: add check-package to "Tips and tricks" 2018-04-02 00:42:59 +02:00
advanced.txt
appendix.txt docs/manual: add appendix about migration from older versions 2017-09-06 22:13:17 +02:00
beyond-buildroot.txt
ccache-support.txt
common-usage.txt support/scripts/graph-depends: use colors instead of colours 2018-04-01 20:01:38 +02:00
configure-other-components.txt
configure.txt docs/manual: drop mention of removed external toolchains 2017-06-20 22:12:54 +02:00
contribute.txt docs/manual: add check-package to "Tips and tricks" 2018-04-02 00:42:59 +02:00
customize-configuration.txt
customize-device-permission-tables.txt
customize-directory-structure.txt docs/manual: document the br2-external NAME 2016-10-16 13:01:02 +02:00
customize-outside-br.txt docs/manual: fix BR2_EXTERNAL path typo 2017-10-15 15:47:59 +02:00
customize-packages.txt docs/manual: document the br2-external NAME 2016-10-16 13:01:02 +02:00
customize-patches.txt
customize-post-image.txt
customize-quick-guide.txt
customize-rootfs.txt docs/manual: document BR2_ROOTFS_POST_FAKEROOT_SCRIPT 2016-07-04 15:22:57 +02:00
customize-users-tables.txt
customize.txt
debugging-buildroot.txt
developers.txt Manual: DEVELOPERS file integrity check 2017-11-08 13:20:02 +01:00
download-infra.txt
download-location.txt docs/manual: centralize recommendations about BR2_DL_DIR 2017-02-07 14:55:02 +01:00
eclipse-integration.txt
faq-troubleshooting.txt manual: remove references to host/usr paths 2017-07-05 16:06:28 +02:00
getting.txt
how-buildroot-works.txt
introduction.txt
known-issues.txt docs: known issues no longer valid 2017-07-01 12:56:21 +02:00
legal-notice.txt docs/manual: refer to SPDX License List 2017-04-01 15:11:18 +02:00
make-tips.txt core: enhance printvars 2017-03-29 21:55:14 +02:00
makedev-syntax.txt
makeusers-syntax.txt
manual.mk manual: get rid of the lists of packages 2016-09-19 19:32:59 +02:00
manual.txt Makefile, manual, website: Bump copyright year 2018-02-01 16:49:41 +01:00
migrating.txt docs/manual: add appendix about $(HOST_DIR)/usr 2017-09-06 22:13:40 +02:00
package-make-target.txt
patch-policy.txt docs: clarify <packagename>_PATCH behaviour 2017-09-24 14:43:37 +02:00
prerequisite.txt docs: Add bc to required tools 2017-01-06 12:18:30 +01:00
quickstart.txt
rebuilding-packages.txt
resources.txt
using-buildroot-debugger.txt manual: remove references to host/usr paths 2017-07-05 16:06:28 +02:00
using-buildroot-development.txt Allow adding per-package override rsync exclusions 2018-04-01 17:05:35 +02:00
using-buildroot-toolchain.txt docs/manual: add documentation for the "make sdk" target 2018-02-25 23:26:28 +01:00
writing-rules.txt tools: rename to 'utils' 2017-07-01 18:07:00 +02:00