[master][blivet] Add CONTRIBUTING file to blivet.

Samantha N. Bueno sbueno+anaconda at redhat.com
Mon Jul 27 14:56:58 UTC 2015


This contains patch submission guidelines for blivet, which are based
on the kernel patch submission guidelines.
---
 CONTRIBUTING | 268 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 268 insertions(+)
 create mode 100644 CONTRIBUTING

diff --git a/CONTRIBUTING b/CONTRIBUTING
new file mode 100644
index 0000000..281e301
--- /dev/null
+++ b/CONTRIBUTING
@@ -0,0 +1,268 @@
+0. Thanks to the kernel patch submission guidelines, which were used as a
+   framework for creating this document.
+
+   https://www.kernel.org/doc/Documentation/SubmittingPatches
+
+I. Source
+=========
+
+A) Obtain a current source tree.
+If you do not have a repository with the current source handy, use git to obtain
+one.  All installer-related projects can be found on the RH Installer project
+page:
+
+  http://github.com/rhinstaller/
+
+Additional help for working within the codebase and testing changes can be found
+on the Fedoraproject wiki:
+
+  https://fedoraproject.org/wiki/Anaconda/Contribute#Helping_with_Anaconda_testing
+
+
+II. Commits
+===========
+    - Considerations when composing your commit message
+    - Special formatting (e.g. for RHEL patches)
+    - Etiquette: when you should split a patch
+
+A) Describe your changes clearly.
+Describe your problem.  Whether your patch is a one-line bug fix or 5000 lines
+of a new feature, there must be an underlying problem that motivated you to do
+this work.  Convince the reviewer that there is a problem worth fixing and that
+it makes sense for them to read past the first paragraph.
+
+Describe user-visible impact.  Straight up crashes and lockups are pretty
+convincing, but not all bugs are that blatant.  Even if the problem was spotted
+during code review, describe the impact you think it can have on users.
+
+Once the problem is established, describe what you are actually doing about it
+in technical detail.  It's important to describe the change in plain English for
+the reviewer to verify that the code is behaving as you intend it to.
+
+Solve only one problem per patch.  If your description starts to get long,
+that's a sign that you probably need to split up your patch.
+
+When you submit or resubmit a patch or patch series, include the complete patch
+description and justification for it.  Don't just say that this is version N of
+the patch (series).  Don't expect the reviewers to refer back to earlier patch
+versions or referenced URLs to find the patch description and put that into the
+patch.
+In other words, the patch (series) and its description should be self-contained.
+
+Describe your changes in imperative mood, e.g. "make xyzzy do frotz" instead of
+"[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if
+you are giving orders to the codebase to change its behaviour.
+
+B) Special considerations for RHEL bugs.
+If you are submitting a patch for any rhel-branch, the last line of your commit
+message must identify the bugzilla bug # it fixes, using the "Resolves" or
+"Related" keyword, e.g.:
+
+    Resolves: rhbz#1111111
+    or
+    Related: rhbz#1234567
+
+Use "Resolves" if the patch fixes the core issue which caused the bug.
+Use "Related" if the patch fixes an ancillary issue that is related to, but
+might not actually fix the bug.
+    
+C) Tracking other history in the commit log.
+In order to easily reference various items related to any patch (set), other
+information should be included in your commit message (after adequately
+describing the problem and your fix). This includes:
+    * GitHub issue, for easy reference back to any scheduled/task list items.
+      Add a line(s):
+        resolves #77
+        or
+        resolves rhinstaller/blivet#14
+
+D) Separate your changes.
+Separate each _logical change_ into a separate patch.
+
+For example, if your changes include both bug fixes and new functionality in a
+single area, separate those changes into two or more patches.  If your changes
+include an API update, and new code which uses that new API, separate those into
+two patches.
+
+On the other hand, if you make a single change to numerous files, group those
+changes into a single patch.  Thus a single logical change is contained within a
+single patch.  The point to remember is that each patch should make an easily
+understood change that can be verified by reviewers.
+
+If one patch depends on another patch in order for a change to be complete, that
+is OK.  Simply note "this patch depends on patch X" in your patch description.
+
+When dividing your change into a series of patches, it is preferred that you
+ensure that the project builds and runs properly after each patch in the series.
+Developers using "git bisect" to track down a problem can end up splitting your
+patch series at any point; they will not thank you if you introduce bugs in the
+middle.
+
+E) Style-check your changes.
+Make sure that the style of your code matches that of the surrounding code.
+
+F) Tests and sanity checking.
+Prior to submitting any patch for review, make sure it runs through pylint
+cleanly. The pylint test can be found in tests/pylint/runpylint.sh
+
+Additionally, creating test files and making sure your changes pass new tests --
+and do not break existing tests -- is crucial. Run "make test" to run the test
+suite.
+
+
+III. Submitting Patches
+=======================
+    - Acceptable formats for patch submission
+    - Email guidelines
+    - Pull Request guidelines
+
+A) Acceptable patch formats.
+GitHub pull requests are accepted.  In fact, they are the preferred format.
+
+Patches can also be sent to anaconda-patches at lists.fedorahosted.org, provided
+they are formatted appropriately (see section III.C).
+
+B) GitHub pull request guidelines
+Labels are used extensively on pull requests in GitHub. Labels make it very easy
+to visually filter a list of pull requests. Labels that we use include:
+    * rhelX-branch -- Any RHEL pull requests should be tagged with the
+      appropriate RHEL branch label (e.g. rhel6-branch, rhel7-branch)
+    * fXY-branch -- Any Fedora pull requests should be tagged with the
+      appropriate Fedora branch label (e.g. f22-branch)
+    * Python 3 check -- If a pull request introduces changes which need to be
+      verified as Python 3 compatible, set this label. (Or someone who reviews
+      your pull request might set this.)
+    * ACK -- Once somebody has reviewed your pull request, they will set the ACK
+      label if your patch is approved.
+    * NACK -- If somebody has reviewed your pull request and disapproves with
+      the patch, they will set the NACK label.
+
+If submitting a patch against multiple branches (e.g. master, rhel7-branch),
+submit the original pull request against master branch. Use labels to tag the
+request for each branch it is intended for.
+
+After approval, merge your commit to master branch. You will have to manually
+cherry pick it to any other branches. Use "git cherry-pick -x $commit" to do
+this, so there is a reference back to the original commit.
+
+C) Email guidelines.
+    i. What to include in your subjects.
+    It is common convention to prefix your subject line with
+    [$project][$branches].  This makes it clear which project the patches are
+    for and which branches the patches are intended for.
+
+    This also applies to lone patches that do not include a cover letter.
+    Examples:
+      Subject: [blivet][master] Move the Blivet class into its own module
+      Subject: [blivet][master/rhel7-branch] Do not unhide devices with hidden
+               parents (#1158643)
+
+    It is common convention to prefix path subject lines with [PATCH].  This
+    makes clear that the message is a patch.
+
+    ii. No MIME, no links, no compression, no attachments.  Just plain text.
+    The developers need to be able to read and comment on the changes you are
+    submitting.  It is important for a developer to be able to "quote" your
+    changes, using standard e-mail tools, so that they may comment on specific
+    portions of your code.
+
+    For this reason, all patches should be submitting e-mail "inline".  WARNING:
+    Be wary of your editor's word-wrap corrupting your patch, if you choose to
+    cut-n-paste your patch.
+
+    Do not attach the patch as a MIME attachment, compressed or not.
+
+    iii. E-mail size.
+    Large changes are not appropriate for mailing listss.  If your patch,
+    uncompressed, exceeds 300 kB in size, it is preferred that you store your
+    patch on a server and provide instead a URL (link) pointing to your patch.
+    But note that if your patch exceeds 300 kB, it almost certainly needs to be
+    broken up anyway.
+
+    iv. Canonical patch format.
+    This section describes how the patch itself should be formatted.  Note that,
+    if you have your patches are stored in a git repository, proper patch
+    formatting can be had with "git format-patch".  The tools cannot create the
+    necessary text, though, so read the instructions anyway.
+
+    Cover letter subject should include the component, the relevant branches,
+    and the relevant bugzilla bug # (if applicable).
+
+    Some examples of the canonical patch subject line:
+        Subject: [PATCH 1/4][blivet][f22-branch] summary phrase (#9999999)
+        Subject: [PATCH 1/3][blivet][master] Split X out of class Y into new
+                 class Z
+
+    The canonical patch message body contains the following:
+      - A "from" line specifying the patch's original author.
+      - An empty line.
+      - The body of the explanation, which will be copied to the permanent
+        changelog to describe this patch.
+      - A marker line containing simply "---".
+      - Any additional comments not suitable for the changelog.
+      - The actual patch (diff output).
+
+    The "summary phrase" in the email's Subject should concisely describe the
+    patch which the email contains in no more than 70-75 characters.  The
+    "summary phrase" should not be a filename.  Do not use the same "summary
+    phrase" for every patch in a whole patch series (where a "patch series" is
+    an ordered sequence of multiple, related patches).  Bear in mind that the
+    "summary phrase" of your email will be the only thing that people may
+    quickly see when they are scanning through patches.
+
+    Tags enclosed in square brackets are not considered part of the "summary
+    phrase", but describe how the patch should be treated.  Common tags might
+    include the patch number/total, e.g. if there are four patches in a series,
+    they may be numbered like this: 1/4, 2/4, 3/4, 4/4.
+
+    The "from" line must be the very first line in the message body, and has the
+    form:
+        From: Original Author <author at example.com>
+
+    The "from" line specifies who will be credited as the author of the patch in
+    the permanent changelog.  If the "from" line is missing, then the "From:"
+    line from the email header will be used to determine the patch author in the
+    changelog.
+
+    Special note to back-porters: It is generally useful when cherry-picking a
+    commit from master onto another branch to use the -x option. This option
+    tells git to insert a note indicating the original commit id, and is often
+    useful.
+
+
+IV. The review process
+======================
+    - What to expect, and when.
+    - Behavioral conduct.
+
+A) Respond to review comments.
+Your patch will almost certainly get comments from reviewers on ways in which
+the patch can be improved.  You must respond to those comments; ignoring
+reviewers is a good way to get ignored in return.  Comments or questions that do
+not result in a code change should almost certainly bring about a comment or
+changelog entry so that the next reviewer better understands what is going on.
+
+Be sure to tell the reviewers what changes you are making and to thank them for
+their time.  Code review is a tiring and time-consuming  process, and reviewers
+sometimes get grumpy.  Even in that case, though, respond politely and address
+the problems they have pointed out.
+
+It is important to understand that patches must sometimes go through several
+iterations of review before being approved.  Not all patches will be accepted
+either.  It is important that you do not take any criticism personally.  Patch
+review is an objective and rational critique only of the content of the patch
+itself.
+
+B) Don't get discouraged - or impatient.
+After you have submitted your change, be patient and wait.  Reviewers are busy
+people and may not get to your patch right away.
+
+You should receive comments within a week or so; if that does not happen, make
+sure that you have sent your patches to the right place.  Wait for a  minimum of
+one week before resubmitting or pinging reviewers - possibly  longer during busy
+times like Fedora release stabilization.
+
+Note that there is a minimum review period of 24 hours for any patch.  The
+purpose of this rule is to ensure that all interested parties have an
+opportunity to review every patch.  When posting a patch before or after a
+holiday break it is important to extend this period as appropriate.
-- 
1.9.3



More information about the anaconda-patches mailing list