[v3.1415] Documentation: add documentation summary for rc-series and merge window

This is losely based on previous discussions on linux-kernel [1][2][3].
Lets also refer people reading the stable rules to
Documentation/development-process/.

Also add the number of days it has taken between releases,
and provide the average for the last 10 releases: 86.0 days.

[1] http://marc.info/?l=linux-kernel&m=122048427801324&w=2
[2] http://marc.info/?l=linux-netdev&m=122048757705315&w=2
[3] http://marc.info/?l=linux-kernel&m=124515657407679&w=2

Signed-off-by: Luis R. Rodriguez <lrodriguez@atheros.com>
---
 Documentation/development-process/2.Process |  158 +++++++++++++++++++++++++--
 Documentation/stable_kernel_rules.txt       |    5 +
 2 files changed, 153 insertions(+), 10 deletions(-)

Luis R. Rodriguez wrote:
> This is losely based on previous discussions on linux-kernel [1][2][3].
> Lets also refer people reading the stable rules to
> Documentation/development-process/.
> 
> Also add the number of days it has taken between releases,
> and provide the average for the last 10 releases: 86.0 days.
> 
> [1] http://marc.info/?l=linux-kernel&m=122048427801324&w=2
> [2] http://marc.info/?l=linux-netdev&m=122048757705315&w=2
> [3] http://marc.info/?l=linux-kernel&m=124515657407679&w=2
> 

I've gone through the patch, and found some typos.

> Signed-off-by: Luis R. Rodriguez <lrodriguez@atheros.com>
> ---
>  Documentation/development-process/2.Process |  158 +++++++++++++++++++++++++--
>  Documentation/stable_kernel_rules.txt       |    5 +
>  2 files changed, 153 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process
> index d750321..d4ca05d 100644
> --- a/Documentation/development-process/2.Process
> +++ b/Documentation/development-process/2.Process
> @@ -7,20 +7,158 @@ course of one year, the kernel has since had to evolve a number of
>  processes to keep development happening smoothly.  A solid understanding of
>  how the process works is required in order to be an effective part of it.
>  
> +2.0:SUMMARY
> +
> +This section provides a brief summary of the kernel release rules.
> +
> +2.0.0: KERNEL RELEASE RULES
> +
> +Stable kernels are released when they are ready! This means there are
> +absolutely no strict guidelines for sticking to specific dates for a
> +kernel release.
> +
> +2.0.1: PATCH QUEUING FOR THE NEXT KERNEL RELEASE
> +
> +Linus maintains the development kernel, this means he accepts new
> +features and drivers for the next kernel release. He however does not
> +maintain every single line of the kernel. The kernel is broken down by
> +different subsystems and each subsystem has its own maintainer. In order

Maybe maintainer(s) ?

> +to aid the development of Linux maintainers subsystem have trees where
> +they queue patches for the next kernel release. This is typically done
> +with a foo-next-2.6.git tree where foo would be an arbitrary subsystem
> +name. These trees typically are designed to have a clean git history
> +to make pulling for Linus easier and as clean as possible.
> +
> +Subsystem maintainers can typically have their own development git trees
> +apart from the foo-next-2.6.git trees as a breeding ground and test ground
> +for bleeding edge patches. Subsystem maintainers are at complete freedom to
> +maintain these trees however they see fit. Once patches have been proven
> +stable enough in a development tree they tend to be moved to their
> +respective foo-next-2.6.git tree.
> +
> +Subsystem development trees are *always* open for development and new patches
> +are always accepted. After a new kernel is released subsystem maintainers
> +tend to slow down in accepting patches into their development trees though
> +so that the new development can eventually be rebased easily ontop of the

on top?

> +next kernel rc1 release.
> +
> +If your patch is adding a new feature or changing a lot of code and you send
> +it between a stable kernel release and prior to the rc1 kernel release it will
> +likely be a while before it is merged into a development tree, so be patient
> +during this time.
> +
> +2.0.1: MERGE WINDOW

2.0.2

> +
> +The merge window opens up after the next stable kernel is released and takes
> +two weeks. The merge window is when maintainers of different subsystems send
> +pull requests to Linus for code they have been queuing up for the next stable
> +kernel. These are the foo-next-2.6.git trees.
> +
> +After the merge window the kernel is worked on through the rc-series of the
> +kernel release. The rc-series focus is to address regressions. The merge window
> +closes upon the first rc-series release, rc1.
> +
> +After a subsystem maintainer has sent his pull request to Linus during the merge
> +window no further new development will be accepted for that foo-next-2.6.git
> +tree and as such it marks the closure of development for that subsystem for that
> +kernel cycle.
> +
> +2.0.2: MEETING DEADLINES FOR KERNEL RELEASES
> +
> +Developers wishing to target deadlines should simply work on their development
> +without regards or consideration for inclusion to a specific kernel release.
> +Once development is done it should simply be posted so the community can review it
> +and it can eventually be merged into the appropriate development subsystem tree.
> +
> +If you insist on targeting a kernel release for deadlines you can try to be aware
> +of the current rc cycle development and how soon it seems the next stable kernel
> +release will be made.
> +
> +A good indication of when the next stable kernel release will be made is when
> +Linus notes the last rc cycle released may be the last. By this time you
> +should already have all your development done and merged in the respective
> +development tree. If your code is not ready and merged into the respective
> +maintainers development tree prior to the announced last potential rc kernel

maintainer's?

> +release chances are you missed getting your code in for the next kernel merge
> +window. Exemptions here are new drivers, covered below.

Exceptions

> +
> +2.0.3: RC-SERIES RULES
> +
> +This section summarizes what kind of patches are accepted after a new stable kernel is
> +released, before the merge window closes and after it closes. These patches are targeted
> +for the kernel prior to its final release.
> +
> +2.0.3.0: RC-SERIES RULES PRIOR TO THE RC1 RELEASE
> +
> +Before the merge window closes, prior to the rc1 release, Linus accepts pull requests
> +from different subsystem maintainers, with it go all the queued up material for the
> +next kernel release for each respective subsystem, on all foo-next-2.6.git trees.
> +After subsystem maintainers have sent their pull requests there are strict rules
> +for new patches prior to the close of the merge window, marked by the rc1 release:
> +
> + - patches must fix a regression
> + - patches must fix a security hole
> + - patches must fix a oops/kernel hang
> +
> +Non-intrusive bug fixes fixes will very likely not be accepted. Some maintainers

2 "fixes"

> +may choose to accept some non-intrusive patches, depending on their work load.
> +You should however not take it for granted such patches will get accepted. You
> +should always just target the development kernel and provide a good commit to
> +help with review.
> +
> +When in doubt consult with your subsystem maintainer or just allow him to
> +do the judging of where the patches deserves to go to, an excellent commit log
> +should help with this effort.
> +
> +2.0.3.1: RC-SERIES RULES AFTER THE RC1 RELEASE
> +
> +Linus does not accept more pull requests from subsystem maintainers after the
> +rc1 release. This means you can expect no new features or new development after
> +rc1.
> +
> +The same type of patches are accepted after the rc1 release with the addition
> +of a slight warmer welcome for non-intrusive bug fix patches. Non-intrusive
> +bug fixes must be important and address very clearly the bug they are fixing.
> +Non-intrusive bug fixes can fix issues which are not a regression, security
> +hole or a kernel oops/hang.
> +
> +Linus will not accept non-intrusive bug fix patches late in the rc-series, after
> +the rc5, for example.
> +
> +You should never take it for granted non-intrusive bug fixes will be accepted.
> +Ultimately it is up to the subsystem maintainers to decide whether to accept
> +such a fix or not, which is why your commit log entry is critically important.
> +You want to provide as much detail as is posisible in order to help maintainers

You need to? Your should?

> +make the right call.
> +
> +2.0.4 RC-SERIES NEW DRIVER EXEMPTION RULE

EXCEPTION

> +
> +The very first release a new driver or filesystem is special. New drivers
> +are accepted during the rc-series! Patches for the same driver then are
> +also accepted during the same rc-series of a kernel as well as fixes for it
> +cannot regress as no previous kernels exists with it.

s/exists/exist

> +
> +After a driver has been present for one kernel release the relaxed rules for
> +it during the rc-series are no longer applicable.
>  
>  2.1: THE BIG PICTURE
>  
>  The kernel developers use a loosely time-based release process, with a new
> -major kernel release happening every two or three months.  The recent
> -release history looks like this:
> -
> -	2.6.26	July 13, 2008
> -	2.6.25	April 16, 2008
> -	2.6.24	January 24, 2008
> -	2.6.23	October 9, 2007
> -	2.6.22	July 8, 2007
> -	2.6.21	April 25, 2007
> -	2.6.20	February 4, 2007
> +major kernel release happening about every two or three months. The current
> +average time based on the last 10 releases is 86.0 days. The recent release
> +history along with the number of days between each release looks like this:
> +
> +	2.6.30	June 10, 2009 - 78 days
> +	2.6.29  March 23, 2009 - 89 days
> +	2.6.28	December 29, 2008 - 76 days
> +	2.6.27	October 8, 2008 - 88 days
> +	2.6.26	July 13, 2008 - 88 days
> +	2.6.25	April 16, 2008 - 83 days
> +	2.6.24	January 24, 2008 - 108 days
> +	2.6.23	October 9, 2007 - 94 days
> +	2.6.22	July 8, 2007 - 75 days
> +	2.6.21	April 25, 2007 - 81 days
> +	2.6.20	February 4, 2007 - 68
>  
>  Every 2.6.x release is a major kernel release with new features, internal
>  API changes, and more.  A typical 2.6 release can contain over 10,000
> diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt
> index a452227..113e8c8 100644
> --- a/Documentation/stable_kernel_rules.txt
> +++ b/Documentation/stable_kernel_rules.txt
> @@ -1,5 +1,10 @@
>  Everything you ever wanted to know about Linux 2.6 -stable releases.
>  
> +For further details, such as stable kernel release schedules, rc-series
> +policies and process of development please refer to:
> +
> +Documentation/development-process/
> +
>  Rules on what kind of patches are accepted, and which ones are not, into the
>  "-stable" tree:
>  
--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

"Luis R. Rodriguez" <lrodriguez@atheros.com> writes:

Hi Luis,

A few comments:

> +2.0:SUMMARY
> +
> +This section provides a brief summary of the kernel release rules.

Is there a reason not to renumber this whole file, making this section
2.1 and incrementing everything else further down?  It just stands out
from the rest of the document by having a 2.0 section, as well as having
all of the 2.0.x subsections.  It's probably fairly minor, but it does
make this chunk look very different than the rest of the
development-process document ...

> +
> +2.0.0: KERNEL RELEASE RULES
> +
> +Stable kernels are released when they are ready! This means there are
> +absolutely no strict guidelines for sticking to specific dates for a
> +kernel release.

The bang (!) seems unneeded.

The second sentence seems to have an overabundance of modifiers, perhaps
something like: This means there are no strict guidelines, in terms of
specific dates, for a kernel release.

> +
> +2.0.1: PATCH QUEUING FOR THE NEXT KERNEL RELEASE
> +
> +Linus maintains the development kernel, this means he accepts new
> +features and drivers for the next kernel release. He however does not
> +maintain every single line of the kernel. The kernel is broken down by
> +different subsystems and each subsystem has its own maintainer. In order
> +to aid the development of Linux maintainers subsystem have trees where
> +they queue patches for the next kernel release. This is typically done
> +with a foo-next-2.6.git tree where foo would be an arbitrary subsystem
> +name. These trees typically are designed to have a clean git history
> +to make pulling for Linus easier and as clean as possible.

I don't quite follow: In order to aid the development of Linux
maintainers subsystem have trees ...

is there a missing comma and/or some missing words?

Is the "foo-next-2.6.git" convention that widespread?  It just seems
like subsystem maintainers have various ways they track things for the
next development release, but maybe I am wrong.  If not, though, perhaps
toning "typically done" down some, and using it as an example of how it
*might* be done, would be better.


> +
> +Subsystem maintainers can typically have their own development git trees
> +apart from the foo-next-2.6.git trees as a breeding ground and test ground
> +for bleeding edge patches. Subsystem maintainers are at complete freedom to
> +maintain these trees however they see fit. Once patches have been proven
> +stable enough in a development tree they tend to be moved to their
> +respective foo-next-2.6.git tree.

as a breeding and testing ground for bleeding edge patches. (sounds
better i think)

> +Subsystem development trees are *always* open for development and new patches
> +are always accepted. After a new kernel is released subsystem maintainers
> +tend to slow down in accepting patches into their development trees though
> +so that the new development can eventually be rebased easily ontop of the
> +next kernel rc1 release.

The first sentence seems to overstate the case somewhat ... new patches
are welcome most any time, not necessarily accepted ... I suspect (but
don't know for sure) that there are times when subsystem trees are
"closed" as well, but maybe not officially

> +If your patch is adding a new feature or changing a lot of code and you send
> +it between a stable kernel release and prior to the rc1 kernel release it will
> +likely be a while before it is merged into a development tree, so be patient
> +during this time.

"between a stable kernel release and prior to the rc1 kernel release"
sounds like "during the merge window"

> +After the merge window the kernel is worked on through the rc-series of the
> +kernel release. The rc-series focus is to address regressions. The merge window
> +closes upon the first rc-series release, rc1.

to address regressions and fix bugs introduced by the new features added
during the merge window.

> +After a subsystem maintainer has sent his pull request to Linus during the merge
> +window no further new development will be accepted for that foo-next-2.6.git
> +tree and as such it marks the closure of development for that subsystem for that
> +kernel cycle.

and, as such, it marks

> +Developers wishing to target deadlines should simply work on their development
> +without regards or consideration for inclusion to a specific kernel
> +release.

That seems a little strange to say ... if they wish to target deadlines,
they can't work without consideration for inclusion into a specific
kernel, can they?

I think you are trying to suggest that they *not* target deadlines, but
that if they must ...

> +A good indication of when the next stable kernel release will be made is when
> +Linus notes the last rc cycle released may be the last. By this time you
> +should already have all your development done and merged in the respective
> +development tree. If your code is not ready and merged into the respective
> +maintainers development tree prior to the announced last potential rc kernel
> +release chances are you missed getting your code in for the next kernel merge
> +window. Exemptions here are new drivers, covered below.

prior to the last rc kernel release, chances are ...

(Li Zefan had some corrections in here, that I won't repeat)

> +This section summarizes what kind of patches are accepted after a new stable kernel is
> +released, before the merge window closes and after it closes. These patches are targeted
> +for the kernel prior to its final release.

before and after the merge window closes.

These patches are targeted for the new kernel currently under
development. (or something like that, "targeted for the kernel prior to
its final release" doesn't make sense, at least to me)


> +Before the merge window closes, prior to the rc1 release, Linus accepts pull requests
> +from different subsystem maintainers, with it go all the queued up material for the
> +next kernel release for each respective subsystem, on all foo-next-2.6.git trees.

This could be simplified substantially: Before the merge window closes,
Linus accepts pull requests from the subsystem maintainers; these
contain all of the queued up patches for that subsystem that are bound
for the next kernel release.

> +After subsystem maintainers have sent their pull requests there are strict rules
> +for new patches prior to the close of the merge window, marked by the
> +rc1 release:

It doesn't seem like you need to keep stressing that the merge window
closes with -rc1 ... but maybe that's just me ...

> +
> + - patches must fix a regression
> + - patches must fix a security hole
> + - patches must fix a oops/kernel hang
> +
> +Non-intrusive bug fixes fixes will very likely not be accepted. Some maintainers
> +may choose to accept some non-intrusive patches, depending on their work load.
> +You should however not take it for granted such patches will get accepted. You
> +should always just target the development kernel and provide a good commit to
> +help with review.

I think you mean "intrusive bug fixes", but maybe not ... maybe the
distinction isn't on the intrusiveness, so much as how
critical/important the fix is ... this also seems overly concrete, in
that various maintainers have their own style which may or may not
conform to this ...

> +When in doubt consult with your subsystem maintainer or just allow him to
> +do the judging of where the patches deserves to go to, an excellent commit log
> +should help with this effort.

When in doubt, consult with the subsystem maintainer to determine
when the patch should be merged.  A well-written, concise commit log
message will help here.

> +Linus does not accept more pull requests from subsystem maintainers after the
> +rc1 release. This means you can expect no new features or new development after
> +rc1.

Again, seemingly too rigid based on what really happens ... but maybe
this is documenting the "ideal"

> +The same type of patches are accepted after the rc1 release with the addition
> +of a slight warmer welcome for non-intrusive bug fix patches. Non-intrusive
> +bug fixes must be important and address very clearly the bug they are fixing.
> +Non-intrusive bug fixes can fix issues which are not a regression, security
> +hole or a kernel oops/hang.
> +
> +Linus will not accept non-intrusive bug fix patches late in the rc-series, after
> +the rc5, for example.

Again, maybe it's just me, but this 'non-intrusive' distinction doesn't
read quite right ... I guess the problem is that non-intrusive and
regression/security/oops fixes are not mutually exclusive but this
document sometimes reads that way ... there are critical bug fixes that
will be accepted pretty much any time, no matter how intrusive they
are.  There are less critical bug fixes that will be accepted based on
how intrusive they are and where in the cycle the patch is proposed.

> +You should never take it for granted non-intrusive bug fixes will be accepted.

so, when do these non-intrusive bug fixes get accepted?  only pre-merge window?

> +The very first release a new driver or filesystem is special. New drivers
> +are accepted during the rc-series! Patches for the same driver then are
> +also accepted during the same rc-series of a kernel as well as fixes for it
> +cannot regress as no previous kernels exists with it.

No ! needed I don't think ....

> +After a driver has been present for one kernel release the relaxed rules for
> +it during the rc-series are no longer applicable.

except staging drivers?

> +	2.6.20	February 4, 2007 - 68

68 days I presume

jake

On Tue, Jun 23, 2009 at 10:18:40AM -0700, Jake Edge wrote:
> "Luis R. Rodriguez" <lrodriguez@atheros.com> writes:
> 
> Hi Luis,
> 
> A few comments:
> 
> > +2.0:SUMMARY
> > +
> > +This section provides a brief summary of the kernel release rules.
> 
> Is there a reason not to renumber this whole file, making this section
> 2.1 and incrementing everything else further down?  It just stands out
> from the rest of the document by having a 2.0 section, as well as having
> all of the 2.0.x subsections.  It's probably fairly minor, but it does
> make this chunk look very different than the rest of the
> development-process document ...

Yeah.. to be honest I was just being lazy. But you're right. I'll take another
stab at it but will probably need to then start touching other parts of the
current doc I was trying to avoid editing as I think Jonathan already did
a great job on.

> > +
> > +2.0.0: KERNEL RELEASE RULES
> > +
> > +Stable kernels are released when they are ready! This means there are
> > +absolutely no strict guidelines for sticking to specific dates for a
> > +kernel release.
> 
> The bang (!) seems unneeded.

Heh ok.

> The second sentence seems to have an overabundance of modifiers, perhaps
> something like: This means there are no strict guidelines, in terms of
> specific dates, for a kernel release.

OK thanks.

> > +
> > +2.0.1: PATCH QUEUING FOR THE NEXT KERNEL RELEASE
> > +
> > +Linus maintains the development kernel, this means he accepts new
> > +features and drivers for the next kernel release. He however does not
> > +maintain every single line of the kernel. The kernel is broken down by
> > +different subsystems and each subsystem has its own maintainer. In order
> > +to aid the development of Linux maintainers subsystem have trees where
> > +they queue patches for the next kernel release. This is typically done
> > +with a foo-next-2.6.git tree where foo would be an arbitrary subsystem
> > +name. These trees typically are designed to have a clean git history
> > +to make pulling for Linus easier and as clean as possible.
> 
> I don't quite follow: In order to aid the development of Linux
> maintainers subsystem have trees ...
> 
> is there a missing comma and/or some missing words?

Heh I meant subsystem maintainers, will fix.

> Is the "foo-next-2.6.git" convention that widespread?  It just seems
> like subsystem maintainers have various ways they track things for the
> next development release, but maybe I am wrong.  If not, though, perhaps
> toning "typically done" down some, and using it as an example of how it
> *might* be done, would be better.

You're right, thanks, will add that. Since you bring this up, are there
a lot of trees not using the foo-next-2.6.git convention?

> > +Subsystem maintainers can typically have their own development git trees
> > +apart from the foo-next-2.6.git trees as a breeding ground and test ground
> > +for bleeding edge patches. Subsystem maintainers are at complete freedom to
> > +maintain these trees however they see fit. Once patches have been proven
> > +stable enough in a development tree they tend to be moved to their
> > +respective foo-next-2.6.git tree.
> 
> as a breeding and testing ground for bleeding edge patches. (sounds
> better i think)

OK great.

> > +Subsystem development trees are *always* open for development and new patches
> > +are always accepted. After a new kernel is released subsystem maintainers
> > +tend to slow down in accepting patches into their development trees though
> > +so that the new development can eventually be rebased easily ontop of the
> > +next kernel rc1 release.
> 
> The first sentence seems to overstate the case somewhat ... new patches
> are welcome most any time, not necessarily accepted ... I suspect (but
> don't know for sure) that there are times when subsystem trees are
> "closed" as well, but maybe not officially

Thanks for pointing this out, any particular example in mind? But anyway, will
change to account for that.

> > +If your patch is adding a new feature or changing a lot of code and you send
> > +it between a stable kernel release and prior to the rc1 kernel release it will
> > +likely be a while before it is merged into a development tree, so be patient
> > +during this time.
> 
> "between a stable kernel release and prior to the rc1 kernel release"
> sounds like "during the merge window"

You're right, that would make it more consistent.

> > +After the merge window the kernel is worked on through the rc-series of the
> > +kernel release. The rc-series focus is to address regressions. The merge window
> > +closes upon the first rc-series release, rc1.
> 
> to address regressions and fix bugs introduced by the new features added
> during the merge window.

Nice.

> > +After a subsystem maintainer has sent his pull request to Linus during the merge
> > +window no further new development will be accepted for that foo-next-2.6.git
> > +tree and as such it marks the closure of development for that subsystem for that
> > +kernel cycle.
> 
> and, as such, it marks
> 
> > +Developers wishing to target deadlines should simply work on their development
> > +without regards or consideration for inclusion to a specific kernel
> > +release.
> 
> That seems a little strange to say ... if they wish to target deadlines,
> they can't work without consideration for inclusion into a specific
> kernel, can they?

Its possible, I tend to use wireless-testing for example, whether that is
on 2.6.30 or soon 2.6.31, either way I just use John's wireless development
tree and when code is ready its ready.

> I think you are trying to suggest that they *not* target deadlines, but
> that if they must ...

Oh I see, yeah you're right. This could use some more clarification.
What I was trying to say is it is hard to make a judgement call of
when you're work will get merged with certainty, prior to submission
to the development trees and review from the community, and recommending
that work be done on the development trees.

> > +A good indication of when the next stable kernel release will be made is when
> > +Linus notes the last rc cycle released may be the last. By this time you
> > +should already have all your development done and merged in the respective
> > +development tree. If your code is not ready and merged into the respective
> > +maintainers development tree prior to the announced last potential rc kernel
> > +release chances are you missed getting your code in for the next kernel merge
> > +window. Exemptions here are new drivers, covered below.
> 
> prior to the last rc kernel release, chances are ...
> 
> (Li Zefan had some corrections in here, that I won't repeat)
> 
> > +This section summarizes what kind of patches are accepted after a new stable kernel is
> > +released, before the merge window closes and after it closes. These patches are targeted
> > +for the kernel prior to its final release.
> 
> before and after the merge window closes.
> 
> These patches are targeted for the new kernel currently under
> development. (or something like that, "targeted for the kernel prior to
> its final release" doesn't make sense, at least to me)

Will change.

> > +Before the merge window closes, prior to the rc1 release, Linus accepts pull requests
> > +from different subsystem maintainers, with it go all the queued up material for the
> > +next kernel release for each respective subsystem, on all foo-next-2.6.git trees.
> 
> This could be simplified substantially: Before the merge window closes,
> Linus accepts pull requests from the subsystem maintainers; these
> contain all of the queued up patches for that subsystem that are bound
> for the next kernel release.

:D

> > +After subsystem maintainers have sent their pull requests there are strict rules
> > +for new patches prior to the close of the merge window, marked by the
> > +rc1 release:
> 
> It doesn't seem like you need to keep stressing that the merge window
> closes with -rc1 ... but maybe that's just me ...

Point taken.

> > +
> > + - patches must fix a regression
> > + - patches must fix a security hole
> > + - patches must fix a oops/kernel hang
> > +
> > +Non-intrusive bug fixes fixes will very likely not be accepted. Some maintainers
> > +may choose to accept some non-intrusive patches, depending on their work load.
> > +You should however not take it for granted such patches will get accepted. You
> > +should always just target the development kernel and provide a good commit to
> > +help with review.
> 
> I think you mean "intrusive bug fixes", but maybe not 

Nope, I meant non-intrusive bug fixes. Intrusive bug fixes won't get accepted.

> ... maybe the
> distinction isn't on the intrusiveness, so much as how
> critical/important the fix is ... this also seems overly concrete, in
> that various maintainers have their own style which may or may not
> conform to this ...

I am under the impression that during the merge window maintainers generally
won't accept non-intrusive bug fixes. That is, bug fixes which are simple but
yet do not address a specific existing regression, security hole, or kernel
oops/hang.

I suppose this could use some more elaboration since it seems it may not have
been clear what I meant to write.

> > +When in doubt consult with your subsystem maintainer or just allow him to
> > +do the judging of where the patches deserves to go to, an excellent commit log
> > +should help with this effort.
> 
> When in doubt, consult with the subsystem maintainer to determine
> when the patch should be merged.  A well-written, concise commit log
> message will help here.

:D

> > +Linus does not accept more pull requests from subsystem maintainers after the
> > +rc1 release. This means you can expect no new features or new development after
> > +rc1.
> 
> Again, seemingly too rigid based on what really happens ... but maybe
> this is documenting the "ideal"

Well I take it that the maintainers who know they can get away with some excemptions
here don't need to read this to figure that out. But I suppose it may be worth
mentioning excemptions do exist, for the record. BTW, just curious, are there any
examples of this?

> > +The same type of patches are accepted after the rc1 release with the addition
> > +of a slight warmer welcome for non-intrusive bug fix patches. Non-intrusive
> > +bug fixes must be important and address very clearly the bug they are fixing.
> > +Non-intrusive bug fixes can fix issues which are not a regression, security
> > +hole or a kernel oops/hang.
> > +
> > +Linus will not accept non-intrusive bug fix patches late in the rc-series, after
> > +the rc5, for example.
> 
> Again, maybe it's just me, but this 'non-intrusive' distinction doesn't
> read quite right ... I guess the problem is that non-intrusive and
> regression/security/oops fixes are not mutually exclusive but this
> document sometimes reads that way ... there are critical bug fixes that
> will be accepted pretty much any time, no matter how intrusive they
> are.  There are less critical bug fixes that will be accepted based on
> how intrusive they are and where in the cycle the patch is proposed.

Right so I don't think I was conveying what I meant appropriately
and I think this could use some more clarification. The point here was
that patches which do not address a regression, kernel oops/hang, or
security issue but yet are non so intrusive, and may fix something small
may very well likely not get accepted late in the rc series.

> > +You should never take it for granted non-intrusive bug fixes will be accepted.
> 
> so, when do these non-intrusive bug fixes get accepted?  only pre-merge window?

Heh yeah, that should be clarified, I thought it was based on the text that
outlined the development trees and queing patches.

But if you are asking me, yes, non-intrusive changes should ideally go in
the development trees prior to the merge window. And I thought the documention
patch was highlighting that there is also a chance of getting some of these
important non-intrusive changes accepted circa rc1-rc5.

> > +The very first release a new driver or filesystem is special. New drivers
> > +are accepted during the rc-series! Patches for the same driver then are
> > +also accepted during the same rc-series of a kernel as well as fixes for it
> > +cannot regress as no previous kernels exists with it.
> 
> No ! needed I don't think ....

OK.

> > +After a driver has been present for one kernel release the relaxed rules for
> > +it during the rc-series are no longer applicable.
> 
> except staging drivers?

Hm, I consider staging a different chapter.

> > +     2.6.20  February 4, 2007 - 68
> 
> 68 days I presume

Yes, thanks. BTW are you up for taking a stab at this yourself? I'm not sure
when I'll be able to again.

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

On Tue, Jun 23, 2009 at 10:55:33AM -0700, Luis R. Rodriguez wrote:
> > > +After a driver has been present for one kernel release the relaxed rules for
> > > +it during the rc-series are no longer applicable.
> > 
> > except staging drivers?
> 
> Hm, I consider staging a different chapter.

Actually, no, I've been treating drivers/staging/ under the same merge
rules at the moment as the rest of the kernel.

thanks,

greg k-h
--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Jake Edge <jake@lwn.net> writes:

>> +After the merge window the kernel is worked on through the rc-series of the
>> +kernel release. The rc-series focus is to address regressions. The merge window
>> +closes upon the first rc-series release, rc1.
>
> to address regressions and fix bugs introduced by the new features added
> during the merge window.

I would say, to address regressions and fix bugs. Not only those added
recently, though obviously older bugs should have already been fixed.

>> +After a subsystem maintainer has sent his pull request to Linus during the merge
>> +window no further new development will be accepted for that
>> +foo-next-2.6.git

This is IMHO uncertain. Typical, but uncertain. I guess the maintainer
would already know what to do so I'm not sure there is a point to write
it down in this file.

> It doesn't seem like you need to keep stressing that the merge window
> closes with -rc1 ... but maybe that's just me ...

Me2 :-)

>> +Non-intrusive bug fixes fixes will very likely not be accepted.
                      ^^^^^^^^^^^
I guess it depends on many factors, such as importance of the bug vs the
risk at the given point. Intrusive bug fixes are sometimes unavoidable
and there may be simply no better option than applying them at once.

> Again, maybe it's just me, but this 'non-intrusive' distinction doesn't
> read quite right ...

Me2 :-)

> I guess the problem is that non-intrusive and
> regression/security/oops fixes are not mutually exclusive

Precisely. This is about risk vs gain.

> so, when do these non-intrusive bug fixes get accepted?  only
> pre-merge window?

Doesn't make sense. Merge window = new features. Fixes can be accepted
anytime (this obviously includes merge window).

>> +The very first release a new driver or filesystem is special. New drivers
>> +are accepted during the rc-series! Patches for the same driver then are
>> +also accepted during the same rc-series of a kernel as well as fixes for it
>> +cannot regress as no previous kernels exists with it.

Given that fixes are accepted anytime (well, almost, depending on risk
vs gain), then obviously fixes for new driver aren't worse.


Perhaps it's just me :-) but I think we're trying to codify the rules
way too much. The general rules (merge window = new features etc) are
obviously ok but why do we need strict details like intrusive vs
non-intrusive etc? People should just use a common sense and good
judgement and, if in doubt in some particular case, ask. We are unable
to describe all situations in a single text file.

On Tue, 23 Jun 2009 10:55:33 -0700 Luis R. Rodriguez wrote:

> You're right, thanks, will add that. Since you bring this up, are
> there a lot of trees not using the foo-next-2.6.git convention?

Hmm, it seems like I have seen a wide variety of tree names and/or
branch names included in the git pull requests ... also, the tree/branch
names used in linux-next:
http://linux.f-seidel.de/linux-next/pmwiki/pmwiki.php?n=Linux-next.IncludedTrees
seem to be all over the map ...

> > Again, seemingly too rigid based on what really happens ... but
> > maybe this is documenting the "ideal"
> 
> Well I take it that the maintainers who know they can get away with
> some excemptions here don't need to read this to figure that out. But
> I suppose it may be worth mentioning excemptions do exist, for the
> record. BTW, just curious, are there any examples of this?

I think you have created a new word: excemptions :)  I kinda like it,
but I think you mean exceptions.

I think there are multiple examples of new features being merged after
-rc1, but nothing comes to mind immediately ... I think the plan is to
only add features during the merge window, but it occasionally gets
overridden ...

> Yes, thanks. BTW are you up for taking a stab at this yourself? I'm
> not sure when I'll be able to again.

Jon may have some comments, when he has a chance to look ... let's see
where it goes from there ...

jake

On Tue, 23 Jun 2009, Krzysztof Halasa wrote:
> 
> I would say, to address regressions and fix bugs. Not only those added
> recently, though obviously older bugs should have already been fixed.

The thing is, I don't take bug fixes late in the -rc just because they are 
bug fixes.

And I really shouldn't.

If it's an old bug, and doesn't cause an oops or a security issue, it had 
damn well better wait for the next merge window. There is absolutely _no_ 
reason to just blindly "fix bugs" at the end of the rc stage, because 
quite frankly, the risks coming from fixing a bug is often bigger than the 
advantage.

Even "obvious bugs" may be things that people depend on, or that other 
parts of the kernel simply rely on indirectly. For a recent example of 
this, see what happened when we fixed an obvious bug on x86-64 to check 
user space addresses properly: it turns out that 'strnlen_user()' depended 
on the bug ("misfeature"), and had to be fixed when the bug was fixed.

So no. Regressions really are _different_ from "fixing bugs".

Regressions need to be fixed even if it may even re-introduce another 
long-time bug - simply because we're much better off with a _consistent_ 
set of bugs where people can depend on their machine either working or 
not, than with some kind of unstable situation that never gets anywhere 
(we found that out the hard way with both ACPI and power management).

So the end result is:

 - we always want to fix bugs

 - but the primary time to fix bugs is during the merge window

 - after the merge window closes, the effort should be on _regressions_, 
   nothing else.

 - security issues and oopses etc catastrophic bugs obviously need to be 
   handled at any stage.

IOW, "it fixes a bug" is _not_ sufficient. The real issue is "it _really_ 
can't wait to the next merge window", not "bug or not".

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

On Tue, 23 Jun 2009 20:52:02 +0200 Krzysztof Halasa wrote:

> Perhaps it's just me :-) but I think we're trying to codify the rules
> way too much. The general rules (merge window = new features etc) are
> obviously ok but why do we need strict details like intrusive vs
> non-intrusive etc? People should just use a common sense and good
> judgement and, if in doubt in some particular case, ask. We are unable
> to describe all situations in a single text file.

Me2 :)

That may be a flaw in some parts of this doc is that it tries to
get too detailed, too rigid, etc. for a process that is more fluid and
has lots of independent parts each working in its own slightly
different way.  It does seem like there is value in much of what's
here, but there just aren't any black-and-white rules for exactly how
patches are handled.

jake

On Tue, 23 Jun 2009, Jake Edge wrote:

> On Tue, 23 Jun 2009 20:52:02 +0200 Krzysztof Halasa wrote:
> 
> > Perhaps it's just me :-) but I think we're trying to codify the rules
> > way too much. The general rules (merge window = new features etc) are
> > obviously ok but why do we need strict details like intrusive vs
> > non-intrusive etc? People should just use a common sense and good
> > judgement and, if in doubt in some particular case, ask. We are unable
> > to describe all situations in a single text file.
> 
> Me2 :)

Well, I do agree that documenting the rules and making them inflexible 
shouldn't be the primary goal.

But the fact is, "common sense" hasn't worked very well. I consistently 
get pull requests from maintainers that have well-meaning "fix bugs" in 
them, and that cause a lot of totally pointless churn.

In fact, this whole discussion has shown one thing: people still think 
that "bug fix" somehow automatically means that it's appropriate after the 
merge window. That's simply not so. 

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

On Tue, 23 Jun 2009 12:11:52 -0700 (PDT) Linus Torvalds wrote:

> In fact, this whole discussion has shown one thing: people still
> think that "bug fix" somehow automatically means that it's
> appropriate after the merge window. That's simply not so. 

Makes sense.  It certainly is counter-intuitive sometimes, though.
Just to clarify, there would seem to be one other category of bugs that
is reasonable post-merge-window: those introduced by new features (or
bug fixes) that were added during the merge window (i.e. something
found in testing the new code during the -rc cycle). Those don't
necessarily have to be security/oops problems and, for the most part,
can't be regressions (at least for new features).  Or should those
wait, by and large, for the next merge window?

jake

Linus Torvalds <torvalds@linux-foundation.org> writes:

> In fact, this whole discussion has shown one thing: people still think 
> that "bug fix" somehow automatically means that it's appropriate after the 
> merge window. That's simply not so. 

That's why i wrote: gain vs risk.

On Tue, 23 Jun 2009, Krzysztof Halasa wrote:

> Linus Torvalds <torvalds@linux-foundation.org> writes:
> 
> > In fact, this whole discussion has shown one thing: people still think 
> > that "bug fix" somehow automatically means that it's appropriate after the 
> > merge window. That's simply not so. 
> 
> That's why i wrote: gain vs risk.

People really don't seem to be very good at the risk management part. They 
see the gain, they don't think about the risk.

Note: not all maintainers are bad about this. But it tends to be my 
biggest gripe after around -rc3 or so - people send stuff that is good, 
but that really has no real reason not to be delayed.

And as long as people talk about this in terms of "bugs", it's a problem.

It would be much better to talk about it in terms of "Does this _really_ 
have to hit the next release? Honestly? Even though we're supposed to be 
in the calming-down period?"

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

On Tue, Jun 23, 2009 at 12:11 PM, Linus
Torvalds<torvalds@linux-foundation.org> wrote:

> In fact, this whole discussion has shown one thing: people still think
> that "bug fix" somehow automatically means that it's appropriate after the
> merge window. That's simply not so.

And that really was the goal of this documentation extension patch, to
clarify that fact. I'm sure Jonathan can do a better job than what I
am trying though, with the added benefit he won't create words out of
thin air :)

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