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>
---
v3
- add a optional 'that' for readability/understandability

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..f4f867cabb1778 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 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.
+
+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

Thorsten Leemhuis <linux@leemhuis.info> writes:

> 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>
> ---
> v3
> - add a optional 'that' for readability/understandability
>
> 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(+)

Applied, thanks.

jon

On Tue, Nov 05, 2024 at 01:11:08PM +0100, Thorsten Leemhuis wrote:
> diff --git a/Documentation/admin-guide/bug-bisect.rst b/Documentation/admin-guide/bug-bisect.rst
> index 585630d14581c7..f4f867cabb1778 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 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.
> +
> +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
>  ---------------------------
> 

Looks good, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

On Tue, Nov 05, 2024 at 01:11:08PM +0100, Thorsten Leemhuis 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'::
> +

Has linux-next tree remote addition be covered before?

Confused...

-- 
An old man doll... just what I always wanted! - Clara

On 06.11.24 02:04, Bagas Sanjaya wrote:
> On Tue, Nov 05, 2024 at 01:11:08PM +0100, Thorsten Leemhuis 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'::
>> +
> 
> Has linux-next tree remote addition be covered before?

No. That document where this is added does not explain at all how to
clone a git repo or add remotes, it just focuses on the bisection. So I
don't think we need to explain this here.

Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst handles
such things, as it has a different target audience. Should it cover
-next as well? Not sure. I for now decided to focus on this addition.

Ciao, Thorsten

On Wed, Nov 06, 2024 at 06:26:49AM +0100, Thorsten Leemhuis wrote:
> On 06.11.24 02:04, Bagas Sanjaya wrote:
> > On Tue, Nov 05, 2024 at 01:11:08PM +0100, Thorsten Leemhuis 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'::
> >> +
> > 
> > Has linux-next tree remote addition be covered before?
> 
> No. That document where this is added does not explain at all how to
> clone a git repo or add remotes, it just focuses on the bisection. So I
> don't think we need to explain this here.

OK.

> 
> Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst handles
> such things, as it has a different target audience. Should it cover
> -next as well? Not sure. I for now decided to focus on this addition.

I think for those who want to test linux-next, they can simply follow [1].
Maybe we can add a pointer to it.

Thanks.

[1]: https://www.kernel.org/doc/man-pages/linux-next.html

-- 
An old man doll... just what I always wanted! - Clara

On 06.11.24 11:15, Bagas Sanjaya wrote:
> On Wed, Nov 06, 2024 at 06:26:49AM +0100, Thorsten Leemhuis wrote:
>> On 06.11.24 02:04, Bagas Sanjaya wrote:
>>> On Tue, Nov 05, 2024 at 01:11:08PM +0100, Thorsten Leemhuis wrote:
>
>> Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst handles
>> such things, as it has a different target audience. Should it cover
>> -next as well? Not sure. I for now decided to focus on this addition.
> 
> I think for those who want to test linux-next, they can simply follow [1].
> Maybe we can add a pointer to it.
> [1]: https://www.kernel.org/doc/man-pages/linux-next.html

Don't think that's worth it either for this document, as those that want
to bisect -next most of the time will already have retrieved next via
git. And again: providing such a pointer for -next, but not explaining
how to retrieve mainline (which is left to the other document linked
prominently at the top) IMHO makes no sense either.

Ciao, Thorsten

On Wed, Nov 06, 2024 at 11:35:10AM +0100, Thorsten Leemhuis wrote:
> On 06.11.24 11:15, Bagas Sanjaya wrote:
> > On Wed, Nov 06, 2024 at 06:26:49AM +0100, Thorsten Leemhuis wrote:
> >> On 06.11.24 02:04, Bagas Sanjaya wrote:
> >>> On Tue, Nov 05, 2024 at 01:11:08PM +0100, Thorsten Leemhuis wrote:
> >
> >> Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst handles
> >> such things, as it has a different target audience. Should it cover
> >> -next as well? Not sure. I for now decided to focus on this addition.
> > 
> > I think for those who want to test linux-next, they can simply follow [1].
> > Maybe we can add a pointer to it.
> > [1]: https://www.kernel.org/doc/man-pages/linux-next.html
> 
> Don't think that's worth it either for this document, as those that want
> to bisect -next most of the time will already have retrieved next via
> git. And again: providing such a pointer for -next, but not explaining
> how to retrieve mainline (which is left to the other document linked
> prominently at the top) IMHO makes no sense either.

OK, thanks!

-- 
An old man doll... just what I always wanted! - Clara