[PATCH v3] docs: bug-bisect: add a note about bisecting -next

[PATCH v3] docs: bug-bisect: add a note about bisecting -next

[Thorsten Leemhuis]

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

Re: [PATCH v3] docs: bug-bisect: add a note about bisecting -next

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 495 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3] docs: bug-bisect: add a note about bisecting -next

[Thorsten Leemhuis]

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

Re: [PATCH v3] docs: bug-bisect: add a note about bisecting -next

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1238 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3] docs: bug-bisect: add a note about bisecting -next

[Thorsten Leemhuis]

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

Re: [PATCH v3] docs: bug-bisect: add a note about bisecting -next

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1156 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3] docs: bug-bisect: add a note about bisecting -next

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1763 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v3] docs: bug-bisect: add a note about bisecting -next

[Jonathan Corbet]

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