-Patches
+CONTENTS
+ Sending Patches
+ Patching Process
+ Email Format
+ Coding Style
+ Options
+ Various Notes
+ Standards Compliance
+
+Sending Patches
+
+ * send your patches to the mailing list (see ../README) or by
+ github.com pull request.
+
+ * email is accepted as an inline patch with, or without, a git pull
+ request. Pull request emails need to include the patch set for review
+ purposes. See howto-pull-request.txt and ../README for git repository
+ instructions.
+
+ * email attachments are difficult to review and not recommended.
+ Hint: use git send-email.
+
+ * one patch per email.
+ See Email Format.
+
+ * many small patches are preferred over a single large patch. Split
+ patch sets based upon logical functionality. For example: #endif mark
+ ups, compiler warnings, and exit code fixes should all be individual
+ small patches.
- * send your patches to the mailing list or to the upstream maintainer
- (see the AUTHORS and README files)
+ * don't include generated (autotools) files in your patches.
+ Hint: use 'git clean -Xd'.
- * diff -u
+ * don't include po/ (translations) changes to the upstream patches.
+ The po/ stuff is maintained on https://translationproject.org/domain/util-linux.html
+ and updated always before the next release.
- * don't include generated (autotools) stuff to your patches (hint:
- use git clean -Xd)
+ * neutrality: the files in util-linux should be distribution-neutral.
+ Packages like RPMs, DEBs, and the rest, are not provided. They should
+ be available from the distribution.
- * neutrality; The stuff in util-linux should be rather
- distribution-neutral. No RPMs/DEBs/... are provided - get yours
- from your distributor.
+Repositories & Branches
- * patches are delivered via email only. Downloading them from
- internet servers is a pain.
+ * Primary repository is on kernel.org:
+ git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
- * one patch per email, with the changelog in the body of the email.
+ * Backup repository at github.com:
+ git clone https://github.com/util-linux/util-linux.git
- * many small patches are favoured over one big. Break down is done on
- basis of logical functionality; for example #endif mark ups,
- compiler warning and exit codes fixes all should be individual
- small patches.
+ We use this repository to backup kernel.org and for PULL REQUESTS,
+ issues tracking. The master and stable branches are always pushed to
+ the both repositories in the same time.
+
+ It's recommended to use github.com for development.
+
+ * Branches:
+
+ master - continuous development
+ stable/vX.Y - stable releases
+
+ Since version 2.40, the "master" branch remains continuously open and is
+ never subjected to feature freezes. The stabilization process for
+ the upcoming release is exclusively conducted within the "stable/" branches.
+ Upon branching from "master" to "stable/vX.Y," a new tag vX.Y+1-devel
+ is generated to serve as placeholder for git-based versioning (refer to
+ tools/git-version-gen). Subsequently, changes specific to the new release
+ (such as po/ updates) are selectively cherry-picked from "stable/vX.Y" to
+ "master" after the final release.
+
+Patching Process
+
+ * announce it on the mailing list when you are going to work with some
+ particular piece of code for a long time. This helps others to avoid
+ massive merge conflicts. Small or quick work, does not need to be
+ announced.
+
+ * make sure that after applying your patch the file(s) will compile
+ without errors.
+
+ * test that the previously existing program behavior is not altered. If
+ the patch intentionally alters the behavior explain what changed, and
+ the reason for it, in the changelog/commit message.
- * Subject: [PATCH] subsystem: description
+ * only submit changes that you believe are ready to merge. To post a
+ patch for peer review only, state it clearly in the email and use
+ the Subject: [PATCH RFC] ...
+
+ * incorporate reviewer comments in the patches. Resubmitting without
+ changes is neither recommended nor polite.
+
+ * resubmission can be partial or complete. If only a few alterations are
+ needed then resubmit those particular patches. When comments cause a
+ greater effect then resubmit the entire patch set.
+
+ * When resubmitting use the email Subject: [PATCH v2] ...
+ Hint: use the --subject-prefix='PATCH v2' option with 'git format-patch'
+
+ * using a git repository for (re)submissions can make life easier.
+ See howto-pull-request.txt and ../README.
+
+ * all patch submissions are either commented, rejected, or accepted.
+ If the maintainer rejects a patch set it is pointless to resubmit it.
+
+Email Format
+
+ * Subject: [PATCH] subsystem: description.
+
+ * Start the message body with an explanation of the patch, that is, a
+ changelog/commit entry.
* if someone else wrote the patch, they should be credited (and
- blamed) for it. To communicate this, add a line:
+ blamed) for it. To communicate this, add a line like:
From: John Doe <jdoe@wherever.com>
- * add a Signed-off-by line (hint: use "git commit -s")
+ * add a Signed-off-by line.
+ Hint: use git commit -s
The sign-off is a simple line at the end of the explanation for the
- patch, which certifies that you wrote it or otherwise have the
- right to pass it on as a open-source patch. The rules are pretty
- simple: if you can certify the below:
+ patch; which certifies that you wrote it or otherwise have the
+ right to pass it on as an open-source patch. The rules are pretty
+ simple; if you can certify the following:
By making a contribution to this project, I certify that:
consistent with this project or the open source license(s)
involved.
- then you just add a line saying
+ Then you just add a line like:
Signed-off-by: Random J Developer <random@developer.example.org>
- using your real name (sorry, no pseudonyms or anonymous
- contributions.)
+ Use your real name (sorry, no pseudonyms or anonymous contributions.)
+
+ * Next a single line beginning with three hyphen-minus characters (---)
+ and nothing else.
- * for more details see: The perfect patch
- http://userweb.kernel.org/~akpm/stuff/tpp.txt
+ * Followed by the unified diff patch.
-Before sending a patch
+ Note: the mailing list will reject certain content. See ../README.
- * make sure that after patching source files will compile without
- errors.
+Coding Style
- * test that previously existed program behaviour is not
- unintentionally alterred. If you alter the behaviour tell about in
- commit message.
+ * the preferred coding style is based on the linux kernel coding-style.
+ Available here:
-Coding style
+ https://docs.kernel.org/process/coding-style.html
- * the preferred coding style is based on the linux kernel
- Documentation/CodingStyle. For more details see:
+ * use 'FIXME:' with a good description, if you want to inform others
+ that something is not quite right, and you are unwilling to fix the
+ issue in the submitted change.
- http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/CodingStyle
+ * do not use `else' after non-returning functions. For
+ example:
- * Use `FIXME:' and a good description if want to inform others
- something is not quite right, and you are unwilling to fix the
- issue.
+ if (this)
+ err(EXIT_FAIL, "this failed");
+ else
+ err(EXIT_FAIL, "that failed");
-Various notes
+ Is wrong and should be written:
- * The util-linux does not use kernel headers for file system super
+ if (this)
+ err(EXIT_FAIL, "this failed");
+ err(EXIT_FAIL, "that failed");
+
+ * when you use 'if' short-shorthand make sure it does not wrap into
+ multiple lines. In case the shorthand does not look good on one line
+ use the normal "if () else" syntax.
+
+Options
+
+ * The rule of thumb for options is that once they exist, you may not
+ change them, nor change how they work, nor remove them.
+
+ * The following options are well-known, and should not be used for any
+ other purpose:
+
+ -h, --help display usage and exit
+ -V, --version display version and exit
+
+ * Some commands use peculiar options and arguments. These will continue
+ to be supported, but anything like them will not be accepted as new
+ additions. A short list of examples:
+
+ Characters other than '-' to start an option. See '+' in 'more'.
+
+ Using a number as an option. See '-<number>' in 'more'.
+
+ Long options that start with a single '-'. See 'setterm'.
+
+ '-?' is not a synonym for '--help', but is an unknown option
+ resulting in a suggestion to try --help due to a getopt failure.
+
+Various Notes
+
+ * util-linux does not use kernel headers for file system super
blocks structures.
- * Patches relying on features that are not in Linus' tree
- are not accepted.
+ * patches relying on kernel features that are not in Linus Torvalds's
+ tree are not accepted.
+
+Standards Compliance
+
+ Some of the commands maintained in this package have Open Group
+ requirements. These commands are:
+
+ cal
+ col
+ ipcrm
+ ipcs
+ kill
+ line
+ logger
+ mesg
+ more
+ newgrp
+ pg
+ renice
+
+ If you change these tools please make sure it does not create a conflict
+ with the latest standard. For example, it is not recommended to add
+ short command line options before they are part of the standard.
+ Introducing new long options is acceptable.
+
+ The Single UNIX(TM) Specification, Version 2
+ Copyright (C) 1997 The Open Group
+
+ https://pubs.opengroup.org/onlinepubs/7908799/xcuix.html
+
projects / thirdparty / util-linux.git / blobdiff