Explicitly mention how to bisect -next, as nothing in the kernel tree
currently explains that bisects between -next versions won't work well
and it's better to bisect between mainline and -next.

Co-developed-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Mark Brown <broonie@kernel.org>
Reviewed-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
v2:
- slightly change patch descption
- make the text more how-toish to better match the rest of the document

v1: https://lore.kernel.org/all/20241022-doc-bisect-next-v1-1-196c0a60d554@kernel.org/
- initial release
---
 Documentation/admin-guide/bug-bisect.rst | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/Documentation/admin-guide/bug-bisect.rst b/Documentation/admin-guide/bug-bisect.rst
index 585630d14581c7..47264c199247e6 100644
--- a/Documentation/admin-guide/bug-bisect.rst
+++ b/Documentation/admin-guide/bug-bisect.rst
@@ -108,6 +108,27 @@ a fully reliable and straight-forward way to reproduce the regression, too.*
 With that the process is complete. Now report the regression as described by
 Documentation/admin-guide/reporting-issues.rst.
 
+Bisecting linux-next
+--------------------
+
+If you face a problem only happening in linux-next, bisect between the
+linux-next branches 'stable' and 'master'. The following commands will start
+the process for a linux-next tree you added as a remote called 'next'::
+
+  git bisect start
+  git bisect good next/stable
+  git bisect bad next/master
+
+The 'stable' branch refers to the state of linux-mainline the current
+linux-next release (found in the 'master' branch) is based on -- the former
+thus should be free of any problems that show up in -next, but not in Linus'
+tree.
+
+This will bisect across a wide range of changes, some of which you might have
+used in earlier linux-next releases without problems. Sadly there is no simple
+way to avoid checking them: bisecting from one linux-next release to a later
+one (say between 'next-20241020' and 'next-20241021') is impossible, as they
+share no common history.
 
 Additional reading material
 ---------------------------

base-commit: 062d98be0e3f6dcf08e40a1101e967b2eb4fb92f
-- 
2.45.0

Hi Thorsten,

Thanks for this.  A couple of comments.

On Fri,  1 Nov 2024 07:17:06 +0100 Thorsten Leemhuis <linux@leemhuis.info> wrote:
>
> Explicitly mention how to bisect -next, as nothing in the kernel tree
> currently explains that bisects between -next versions won't work well
> and it's better to bisect between mainline and -next.
> 
> Co-developed-by: Mark Brown <broonie@kernel.org>
> Signed-off-by: Mark Brown <broonie@kernel.org>
> Reviewed-by: Mark Brown <broonie@kernel.org>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> v2:
> - slightly change patch descption
> - make the text more how-toish to better match the rest of the document
> 
> v1: https://lore.kernel.org/all/20241022-doc-bisect-next-v1-1-196c0a60d554@kernel.org/
> - initial release
> ---
>  Documentation/admin-guide/bug-bisect.rst | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/Documentation/admin-guide/bug-bisect.rst b/Documentation/admin-guide/bug-bisect.rst
> index 585630d14581c7..47264c199247e6 100644
> --- a/Documentation/admin-guide/bug-bisect.rst
> +++ b/Documentation/admin-guide/bug-bisect.rst
> @@ -108,6 +108,27 @@ a fully reliable and straight-forward way to reproduce the regression, too.*
>  With that the process is complete. Now report the regression as described by
>  Documentation/admin-guide/reporting-issues.rst.
>  
> +Bisecting linux-next
> +--------------------
> +
> +If you face a problem only happening in linux-next, bisect between the
> +linux-next branches 'stable' and 'master'. The following commands will start
> +the process for a linux-next tree you added as a remote called 'next'::
> +
> +  git bisect start
> +  git bisect good next/stable
> +  git bisect bad next/master
> +
> +The 'stable' branch refers to the state of linux-mainline the current
                                                             ^
                                                             that the current

> +linux-next release (found in the 'master' branch) is based on -- the former
> +thus should be free of any problems that show up in -next, but not in Linus'
> +tree.

As you say, 'stable' only works for the current linux-next release.  If
you are trying to bisect a previous release, you can always find the
SHA1 associated with the base of any linux-next release using "grep
origin Next/SHA1s".  Not sure how useful that is.

-- 
Cheers,
Stephen Rothwell

On 01.11.24 12:59, Stephen Rothwell wrote:
>
> Thanks for this.  A couple of comments.

yw; thx for your feedback!

> On Fri,  1 Nov 2024 07:17:06 +0100 Thorsten Leemhuis <linux@leemhuis.info> wrote:
> [...]
>> +Bisecting linux-next
>> +--------------------
>> +
>> +If you face a problem only happening in linux-next, bisect between the
>> +linux-next branches 'stable' and 'master'. The following commands will start
>> +the process for a linux-next tree you added as a remote called 'next'::
>> +
>> +  git bisect start
>> +  git bisect good next/stable
>> +  git bisect bad next/master
>> +
>> +The 'stable' branch refers to the state of linux-mainline the current
>                                                              ^
>                                                              that the current

Ohh, I thought such a "that" would be optional here, but I'm not a
native speaker, so I guess I was wrong.

>> +linux-next release (found in the 'master' branch) is based on -- the former
>> +thus should be free of any problems that show up in -next, but not in Linus'
>> +tree.
> 
> As you say, 'stable' only works for the current linux-next release.  If
> you are trying to bisect a previous release, you can always find the
> SHA1 associated with the base of any linux-next release using "grep
> origin Next/SHA1s".  Not sure how useful that is.

Hmmm. Not sure. Open for opinions here. But right now I tend to think:
nice to know, but not relevant enough for this text, as most people want
to check if latest -next is still affected -- so why then bisect with a
older -next release?

Ciao, Thorsten

Hi Thorsten,

On Sat, 2 Nov 2024 12:28:21 +0100 Thorsten Leemhuis <linux@leemhuis.info> wrote:
>
> On 01.11.24 12:59, Stephen Rothwell wrote:
> >
 > On Fri,  1 Nov 2024 07:17:06 +0100 Thorsten Leemhuis <linux@leemhuis.info> wrote:
> > [...]  
> >> +The 'stable' branch refers to the state of linux-mainline the current  
> >                                                              ^
> >                                                              that the current  
> 
> Ohh, I thought such a "that" would be optional here, but I'm not a
> native speaker, so I guess I was wrong.

Yeah, I guess it is optional, but I prefer it written like that - it
sounds better to my ear.

> >> +linux-next release (found in the 'master' branch) is based on -- the former
> >> +thus should be free of any problems that show up in -next, but not in Linus'
> >> +tree.  
> > 
> > As you say, 'stable' only works for the current linux-next release.  If
> > you are trying to bisect a previous release, you can always find the
> > SHA1 associated with the base of any linux-next release using "grep
> > origin Next/SHA1s".  Not sure how useful that is.  
> 
> Hmmm. Not sure. Open for opinions here. But right now I tend to think:
> nice to know, but not relevant enough for this text, as most people want
> to check if latest -next is still affected -- so why then bisect with a
> older -next release?

That is fine.

-- 
Cheers,
Stephen Rothwell