Kernel patches policy

From Mandriva Community Wiki

Contents 1 The problem(s) 1.1 Work on maintenance of patches 1.2 Documentation of patches 2 Proposal 2.1 Add information about the patches 2.2 Format of the patches 2.2.1 Author and Signed-off fields 2.2.2 Summary phrase 2.2.3 Long description 2.2.4 Reason 2.2.5 Origin 2.2.6 Type 2.2.7 Upstream status 2.3 Less patches, the better 2.4 Enforcing the policy 2.5 Benefits 2.5.1 Listing "What takes us work" 2.5.2 Easier maintenance 2.5.3 Taking decisions

The problem(s)

Work on maintenance of patches

We have lots of patches in our kernel. Ranging from simple bugfixes to added features. Maintaining them takes lots of work.

Documentation of patches

The patches in our kernel have little documentation. We don't have information regarding:

• Where the patch comes from
• Why it was added to our kernel
• Is it a feature or a bugfix?
• Why it is a separated patch and it isn't in the Linus tree yet?

This is also related to the problem on the previous section: we can't generate quickly a list of the patches we have to maintain separatedly (generally because we wanted some feature and decided to take the risk of maintaining the patch in our tree).

Proposal

Add information about the patches

We should have some information about ALL patches added to our package. Listed below.

Some information will be mandatory (preferably all fields will be mandatory).

Format of the patches

The patches should have the format described on section "The canonical patch format" on Documentation/SubmittingPatches.

The recommended tool to be used to generate the patches is git-format-patch.

TODO: Define the format for the additional fields we created (Reason, Origin, Type, Upstream status)

Author and Signed-off fields

The original author of the patch and Signed-off fields MUST be added to the patch, such as described on Documentation/SubmittingPatches.

The reason for that is the same described on Documentation/SubmittingPatches:

To improve tracking of who did what, especially with patches that can
percolate to their final resting place in the kernel through several
layers of maintainers, we've introduced a "sign-off" procedure on
patches that are being emailed around.

Summary phrase

Every patch MUST have a summary phrase. From Documentation/SubmittingPatches:

The "summary phrase" in the email's Subject should concisely
describe the patch which that email contains.  The "summary
phrase" should not be a filename.  Do not use the same "summary
phrase" for every patch in a whole patch series.

Long description

The long description is the "explanation body" as described on Documentation/SubmittingPatches. All patches MUST have an explanation body.

The explanation body will be committed to the permanent source
changelog, so should make sense to a competent reader who has long
since forgotten the immediate details of the discussion that might
have led to this patch.

Reason

The Reason field explains why we have decided to include the patch on the package. It should be preferably a reference to a Mandriva bugzilla ticket, but it is not mandatory. Every patch MUST have a Reason field.

TODO: Define format

Origin

The Origin field tells the reader where the patch came from, how it was found. Use common sense to tell how much information is needed to make sense of this. A good practice would be including a URL in this field.

If the upstream status field is backport, this field MUST tell from which kernel version the patch came from.

If the upstream status field is queued or own-maintenance, this field MUST be filled with information about where the patch was taken from. If it is a different kernel tree, it MUST give a pointer to it. If the patch was taken directly from the author (or the author itself is inserting the patch into the package), the field MAY be set just to "author".

TODO: Define format

Type

The "type" field explains what kind of change the patch refers to. It is a enum value, which means that there will be a limited set of valid values for this field. The change may be:

• An additional feature; or
• A bugfix

This field MUST be filled.

TODO: Define format and where the information will be (either on the patch description or on the patch name)

Upstream status

This field should explain why we are including this change as a patch, and why it is not on the upstream tarball (the Linus tree). It is an enum field, also. It will allow us to tell quickly how many patches we have to maintain ourselves, taking some work to maintain. The possible values for this field would be:

• backport: Backport of change already on Linus tree
• queued: Change will be added soon to Linus tree
• own-maintenance: Change is not on Linus tree and there are no plans to include the change on Linus tree. These patches take more work to maintain.

This field MUST be filled.

TODO: Define format and where the information will be (either on the patch description or on the patch name)

Less patches, the better

In order to minimize the time spent dealing with patches in our kernel, we SHOULD minimize the number of separated patches we have.

• 3rd party drivers: package them separatedly if possible
• Additional features: only add them if it is worth the time spent in maintaining it

Suggestion - Can we have one development team who will look after Mandriva OS only and another team looking after adding new features/3rd party drivers to Mandriva OS. Co-ordinator will co ordinate between two teams. RPM's to be tested, packaged and released seperately.This way both teams will remain focused and Mandriva OS will become more stable distro.

Enforcing the policy

The buildsystem would enforce people to follow the approved documentation policy. Checking for policy conformance may be made on a commit-hook on the version control system, when patches are added to the package, thus unconforming changes may be rejected at commit-time.

TODO: Elaborate the procedure for the buildsystem

Benefits

Listing "What takes us work"

We will to be able to list quickly which changes we have added to our kernel that aren't on the Linus tree. If we keep changes that aren't on the Linus kernel tree, it will take us more work, and we need to have a good reason for the additional work of integration of the patches.

Easier maintenance

Easier maintenance/updating of patches due to good documentation. Sometimes regenerating a patch for a kernel update is hard because the code may have changed too much, and we don't know if there is a more recent version of the patch somewhere, who maintains it, etc. Including the origin, reason, author and signed-off information will make this task easier.

Taking decisions

We will be able to take better decisions about what we want to keep in our kernel. Listing "What takes us work" will allow the Company to decide if we really want to keep some features in the kernel, even having more work.