Adding upstream version 2.38.1.upstream/2.38.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 248 insertions, 0 deletions

diff --git a/Documentation/howto-contribute.txt b/Documentation/howto-contribute.txt
new file mode 100644
index 0000000..fe68c6a
--- /dev/null
+++ b/Documentation/howto-contribute.txt
@@ -0,0 +1,248 @@
+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.
+
+	* don't include generated (autotools) files in your patches.
+	  Hint: use 'git clean -Xd'.
+
+        * don't include po/ (translations) changes to the upstream patches.
+          The po/ stuff is maintained on http://translationproject.org/domain/util-linux.html
+          and updated always before the next release.
+
+	* 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.
+
+Repositories & Branches
+
+	* Primary repository is on kernel.org:
+          git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
+
+	  We use this repository for master and stable branches only.
+
+	* Backup repository at github.com:
+	  git clone git://github.com/util-linux/util-linux.git
+
+	  We use this repository to backup kernel.org and for pull requests,
+	  issues tracking and topic branches. 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   - development for the next release
+	  stable/* - stable maintenance releases
+
+	  Github only:
+
+	  next	   - optionally used when master branch is frozen due to -rcN releases
+	  topic/*  - long time development
+
+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.
+
+	* 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 like:
+
+	  From: John Doe <jdoe@wherever.com>
+
+	* 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 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:
+
+	   (a) The contribution was created in whole or in part by me and I
+	       have the right to submit it under the open source license
+	       indicated in the file; or
+
+	   (b) The contribution is based upon previous work that, to the best
+	       of my knowledge, is covered under an appropriate open source
+	       license and I have the right under that license to submit that
+	       work with modifications, whether created in whole or in part
+	       by me, under the same open source license (unless I am
+	       permitted to submit under a different license), as indicated
+	       in the file; or
+
+	   (c) The contribution was provided directly to me by some other
+	       person who certified (a), (b) or (c) and I have not modified
+	       it.
+
+	   (d) I understand and agree that this project and the contribution
+	       are public and that a record of the contribution (including
+	       all personal information I submit with it, including my
+	       sign-off) is maintained indefinitely and may be redistributed
+	       consistent with this project or the open source license(s)
+	       involved.
+
+	  Then you just add a line like:
+
+	       Signed-off-by: Random J Developer <random@developer.example.org>
+
+	  Use your real name (sorry, no pseudonyms or anonymous contributions.)
+
+	* Next a single line beginning with three hyphen-minus characters (---)
+	  and nothing else.
+
+	* Followed by the unified diff patch.
+
+	Note: the mailing list will reject certain content. See ../README.
+
+Coding Style
+
+	* the preferred coding style is based on the linux kernel coding-style.
+	  Available here:
+
+	http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/coding-style.rst
+
+	* 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.
+
+	* do not use `else' after non-returning functions. For
+	  example:
+
+	  if (this)
+		err(EXIT_FAIL, "this failed");
+	  else
+		err(EXIT_FAIL, "that failed");
+
+	  Is wrong and should be written:
+
+	  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 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
+
+		http://pubs.opengroup.org/onlinepubs/7908799/xcuix.html
+