Re: [PATCH 2/4] doc-rst: admin-guide: move bug bisect to a separate file

2016-11-07 Thread Jonathan Corbet 
On Mon, 7 Nov 2016 23:13:03 -0200
Mauro Carvalho Chehab  wrote:

> Argh! PDF output is really fragile. I would change it then to:
> 
> .. [#f1] You can, optionally, provide both good and bad arguments at git
>start: ``git bisect start [BAD] [GOOD]``
> 
> Do you want me to write such patch or are you committing one yourself?

I've already made exactly that change - ahead of you for once! :)

I'm trying to track down some other weirdness, though, before I'm ready
to push docs-next.  I may have to give up soon and deal with it tomorrow.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/4] doc-rst: admin-guide: move bug bisect to a separate file

2016-11-07 Thread Mauro Carvalho Chehab 
Em Mon, 7 Nov 2016 17:39:02 -0700
Jonathan Corbet  escreveu:

> On Mon,  7 Nov 2016 17:03:17 -0200
> Mauro Carvalho Chehab  wrote:
> 
> > +.. [#f1] You can, optionally, provide both good and bad arguments at git
> > +start::
> > +
> > +   git bisect start [BAD] [GOOD]  
> 
> So this, as it turns out, kills the PDF build:
> 
> Markup is unsupported in LaTeX:
> admin-guide/bug-bisect:71: literal blocks in footnotes are not supported by 
> LaTeX
> Documentation/Makefile.sphinx:72: recipe for target 'latexdocs' failed
> 
> Not quite sure why I didn't run into it before, since it's not really new
> with this patch... I'll probably tack on a small fix to make things work
> again.

Argh! PDF output is really fragile. I would change it then to:

.. [#f1] You can, optionally, provide both good and bad arguments at git
 start: ``git bisect start [BAD] [GOOD]``

Do you want me to write such patch or are you committing one yourself?

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/4] doc-rst: admin-guide: move bug bisect to a separate file

2016-11-07 Thread Mauro Carvalho Chehab 
Em Mon, 7 Nov 2016 16:55:26 -0700
Jonathan Corbet  escreveu:

> On Mon,  7 Nov 2016 17:03:17 -0200
> Mauro Carvalho Chehab  wrote:
> 
> > Better organize the admin guide documentation by moving the
> > bug bisect to a separate file.
> > 
> > Signed-off-by: Mauro Carvalho Chehab 
> > ---
> >  Documentation/admin-guide/bug-bisect.rst  | 78 
> > +++
> >  Documentation/admin-guide/bug-hunting.rst | 74 
> > -
> >  Documentation/admin-guide/index.rst   |  1 +
> >  3 files changed, 79 insertions(+), 74 deletions(-)
> >  create mode 100644 Documentation/admin-guide/bug-bisect.rst
> > 
> > diff --git a/Documentation/admin-guide/bug-bisect.rst 
> > b/Documentation/admin-guide/bug-bisect.rst
> > new file mode 100644
> > index ..5682d742017c
> > --- /dev/null
> > +++ b/Documentation/admin-guide/bug-bisect.rst
> > @@ -0,0 +1,78 @@
> > +Bisecting a bug
> > 
> > +
> > +Last updated: 28 October 2016  
> 
> So I wonder if we really need lines like that?  That's what Git is for,
> especially since people often don't update the "last updated" lines...:)

Yeah, I guess we could strip those last updated on ReST files.

> 
> > +Introduction
> > +
> > +
> > +Always try the latest kernel from kernel.org and build from source. If you 
> > are
> > +not confident in doing that please report the bug to your distribution 
> > vendor
> > +instead of to a kernel developer.
> > +
> > +Finding bugs is not always easy. Have a go though. If you can't find it 
> > don't
> > +give up. Report as much as you have found to the relevant maintainer. See
> > +MAINTAINERS for who that is for the subsystem you have worked on.
> > +
> > +Before you submit a bug report read
> > +:ref:`Documentation/admin-guide/reporting-bugs.rst `.
> > +
> > +Devices not appearing
> > +=
> > +
> > +Often this is caused by udev/systemd. Check that first before blaming it
> > +on the kernel.  
> 
> A proper document should, of course, tell the poor user just how they are
> supposed to do that.  

Agreed. Well, we could add some notes here explaining more about
device probing, sysfs (and perhaps lspci), but maybe there's something
already explained on on the remaining docs.

> Anyway, I've applied the set of four.  I'm still not sure about keeping
> some of that stuff around, but the result is clearly better than what we
> had before.

Thanks! Yeah, we can improve the remaining issues later.

> One quick request: could you copy me on the 0/n cover letter when you do a
> series like this?  As it is, I get the patches, but have to go digging
> through the list for the cover.

Ok, I'll do it.

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/4] doc-rst: admin-guide: move bug bisect to a separate file

2016-11-07 Thread Jonathan Corbet 
On Mon,  7 Nov 2016 17:03:17 -0200
Mauro Carvalho Chehab  wrote:

> +.. [#f1] You can, optionally, provide both good and bad arguments at git
> +  start::
> +
> + git bisect start [BAD] [GOOD]

So this, as it turns out, kills the PDF build:

Markup is unsupported in LaTeX:
admin-guide/bug-bisect:71: literal blocks in footnotes are not supported by 
LaTeX
Documentation/Makefile.sphinx:72: recipe for target 'latexdocs' failed

Not quite sure why I didn't run into it before, since it's not really new
with this patch... I'll probably tack on a small fix to make things work
again.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/4] doc-rst: admin-guide: move bug bisect to a separate file

2016-11-07 Thread Jonathan Corbet 
On Mon,  7 Nov 2016 17:03:17 -0200
Mauro Carvalho Chehab  wrote:

> Better organize the admin guide documentation by moving the
> bug bisect to a separate file.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/admin-guide/bug-bisect.rst  | 78 
> +++
>  Documentation/admin-guide/bug-hunting.rst | 74 -
>  Documentation/admin-guide/index.rst   |  1 +
>  3 files changed, 79 insertions(+), 74 deletions(-)
>  create mode 100644 Documentation/admin-guide/bug-bisect.rst
> 
> diff --git a/Documentation/admin-guide/bug-bisect.rst 
> b/Documentation/admin-guide/bug-bisect.rst
> new file mode 100644
> index ..5682d742017c
> --- /dev/null
> +++ b/Documentation/admin-guide/bug-bisect.rst
> @@ -0,0 +1,78 @@
> +Bisecting a bug
> 
> +
> +Last updated: 28 October 2016

So I wonder if we really need lines like that?  That's what Git is for,
especially since people often don't update the "last updated" lines...:)

> +Introduction
> +
> +
> +Always try the latest kernel from kernel.org and build from source. If you 
> are
> +not confident in doing that please report the bug to your distribution vendor
> +instead of to a kernel developer.
> +
> +Finding bugs is not always easy. Have a go though. If you can't find it don't
> +give up. Report as much as you have found to the relevant maintainer. See
> +MAINTAINERS for who that is for the subsystem you have worked on.
> +
> +Before you submit a bug report read
> +:ref:`Documentation/admin-guide/reporting-bugs.rst `.
> +
> +Devices not appearing
> +=
> +
> +Often this is caused by udev/systemd. Check that first before blaming it
> +on the kernel.

A proper document should, of course, tell the poor user just how they are
supposed to do that.  

Anyway, I've applied the set of four.  I'm still not sure about keeping
some of that stuff around, but the result is clearly better than what we
had before.

One quick request: could you copy me on the 0/n cover letter when you do a
series like this?  As it is, I get the patches, but have to go digging
through the list for the cover.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/4] doc-rst: admin-guide: move bug bisect to a separate file

2016-11-07 Thread Mauro Carvalho Chehab 
Better organize the admin guide documentation by moving the
bug bisect to a separate file.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/admin-guide/bug-bisect.rst  | 78 +++
 Documentation/admin-guide/bug-hunting.rst | 74 -
 Documentation/admin-guide/index.rst   |  1 +
 3 files changed, 79 insertions(+), 74 deletions(-)
 create mode 100644 Documentation/admin-guide/bug-bisect.rst

diff --git a/Documentation/admin-guide/bug-bisect.rst 
b/Documentation/admin-guide/bug-bisect.rst
new file mode 100644
index ..5682d742017c
--- /dev/null
+++ b/Documentation/admin-guide/bug-bisect.rst
@@ -0,0 +1,78 @@
+Bisecting a bug

+
+Last updated: 28 October 2016
+
+Introduction
+
+
+Always try the latest kernel from kernel.org and build from source. If you are
+not confident in doing that please report the bug to your distribution vendor
+instead of to a kernel developer.
+
+Finding bugs is not always easy. Have a go though. If you can't find it don't
+give up. Report as much as you have found to the relevant maintainer. See
+MAINTAINERS for who that is for the subsystem you have worked on.
+
+Before you submit a bug report read
+:ref:`Documentation/admin-guide/reporting-bugs.rst `.
+
+Devices not appearing
+=
+
+Often this is caused by udev/systemd. Check that first before blaming it
+on the kernel.
+
+Finding patch that caused a bug
+===
+
+Using the provided tools with ``git`` makes finding bugs easy provided the bug
+is reproducible.
+
+Steps to do it:
+
+- build the Kernel from its git source
+- start bisect with [#f1]_::
+
+   $ git bisect start
+
+- mark the broken changeset with::
+
+   $ git bisect bad [commit]
+
+- mark a changeset where the code is known to work with::
+
+   $ git bisect good [commit]
+
+- rebuild the Kernel and test
+- interact with git bisect by using either::
+
+   $ git bisect good
+
+  or::
+
+   $ git bisect bad
+
+  depending if the bug happened on the changeset you're testing
+- After some interactions, git bisect will give you the changeset that
+  likely caused the bug.
+
+- For example, if you know that the current version is bad, and version
+  4.8 is good, you could do::
+
+   $ git bisect start
+   $ git bisect bad # Current version is bad
+   $ git bisect good v4.8
+
+
+.. [#f1] You can, optionally, provide both good and bad arguments at git
+start::
+
+   git bisect start [BAD] [GOOD]
+
+For further references, please read:
+
+- The man page for ``git-bisect``
+- `Fighting regressions with git bisect 
`_
+- `Fully automated bisecting with "git bisect run" 
`_
+- `Using Git bisect to figure out when brokenness was introduced 
`_
diff --git a/Documentation/admin-guide/bug-hunting.rst 
b/Documentation/admin-guide/bug-hunting.rst
index 818b3e09267f..d245d4677ae2 100644
--- a/Documentation/admin-guide/bug-hunting.rst
+++ b/Documentation/admin-guide/bug-hunting.rst
@@ -3,80 +3,6 @@ Bug hunting
 
 Last updated: 28 October 2016
 
-Introduction
-
-
-Always try the latest kernel from kernel.org and build from source. If you are
-not confident in doing that please report the bug to your distribution vendor
-instead of to a kernel developer.
-
-Finding bugs is not always easy. Have a go though. If you can't find it don't
-give up. Report as much as you have found to the relevant maintainer. See
-MAINTAINERS for who that is for the subsystem you have worked on.
-
-Before you submit a bug report read
-:ref:`Documentation/admin-guide/reporting-bugs.rst `.
-
-Devices not appearing
-=
-
-Often this is caused by udev/systemd. Check that first before blaming it
-on the kernel.
-
-Finding patch that caused a bug
-===
-
-Using the provided tools with ``git`` makes finding bugs easy provided the bug
-is reproducible.
-
-Steps to do it:
-
-- build the Kernel from its git source
-- start bisect with [#f1]_::
-
-   $ git bisect start
-
-- mark the broken changeset with::
-
-   $ git bisect bad [commit]
-
-- mark a changeset where the code is known to work with::
-
-   $ git bisect good [commit]
-
-- rebuild the Kernel and test
-- interact with git bisect by using either::
-
-   $ git bisect good
-
-  or::
-
-   $ git bisect bad
-
-  depending if the bug happened on the changeset you're testing
-- After some interactions, git bisect will give you the changeset that
-  likely caused the bug.
-
-- For example, if you know that the current version is bad, and version
-  4.8 is good, you could do::
-
-   $ git bisect start
-   $ git bisect bad # Current version is bad
-   $ git bisect good v4.8
-
-