doc: Document challenges of tags with git fetcher

Using tags with the git fetcher may cause surprising behaviour. There
are reasons for this, document them.

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 7 +++++++
 1 file changed, 7 insertions(+)

On Sat, Sep 2, 2023 at 12:55, Richard Purdie <[richard.purdie@linuxfoundation.org](mailto:On Sat, Sep 2, 2023 at 12:55, Richard Purdie <<a href=)> wrote:

> Using tags with the git fetcher may cause surprising behaviour. There
> are reasons for this, document them.
>
> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
> ---
> doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 7 +++++++
> 1 file changed, 7 insertions(+)
>
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> index f5723d6767..91538f4059 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> @@ -476,6 +476,13 @@ Here are some example URLs::
> easy to share metadata without removing passwords. SSH keys, ``~/.netrc``
> and ``~/.ssh/config`` files can be used as alternatives.
>
> +Using tags with the git fetcher may cause surprising behaviour. Bitbake needs to
> +resolve the tag to a specific revision and to do that, it has to connect to and use
> +the upstream repository. This is because the revision tags point at can change and
> +we've cases of this happening in well known public repositories. This can mean many
> +more network connections than expected, source mirrors may be bypassed and recipes
> +may
>
>> and
>> +we've cases of this happening in well known public repositories
>
> reparsed when not expected. For these reasons, whilst the fetcher can support
> +tags, we recommend being specific about revisions in recipes.
>
> .. _gitsm-fetcher:
>
> --
> 2.39.2
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#15004): https://lists.openembedded.org/g/bitbake-devel/message/15004
> Mute This Topic: https://lists.openembedded.org/mt/101111607/4454782
> Group Owner: bitbake-devel+owner@lists.openembedded.org
> Unsubscribe: https://lists.openembedded.org/g/bitbake-devel/leave/12051247/4454782/107362028/xyzzy [paulo@myneves.com]
> -=-=-=-=-=-=-=-=-=-=-=-

>

> and
> +we've cases of this happening in well known public repositories

Historically this happened with well known public repositories.

Why can source mirrors be bypassed? Because the hash changed and the mirror does not have it? If so it would be nice to clarify it.

Hi Richard,

On 9/2/23 12:55, Richard Purdie via lists.openembedded.org wrote:
> Using tags with the git fetcher may cause surprising behaviour. There
> are reasons for this, document them.
> 
> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
> ---
>   doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 7 +++++++
>   1 file changed, 7 insertions(+)
> 
> diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> index f5723d6767..91538f4059 100644
> --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst
> @@ -476,6 +476,13 @@ Here are some example URLs::
>      easy to share metadata without removing passwords. SSH keys, ``~/.netrc``
>      and ``~/.ssh/config`` files can be used as alternatives.
>   
> +Using tags with the git fetcher may cause surprising behaviour. Bitbake needs to
> +resolve the tag to a specific revision and to do that, it has to connect to and use
> +the upstream repository. This is because the revision tags point at can change and
> +we've cases of this happening in well known public repositories. This can mean many

Intuitively, I think "seen" or "had" is missing in "we've cases".

Otherwise, same question as Paulo, so will look for follow-up on that 
other mail :)

Cheers,
Quentin