Submitting patches

Setting up user information

Please set up consistent user information before starting with your real name and working
email address on all your computers (for example the same email addressed that is subscribed
erlang-patches mailing list). For quick reference, here are the needed commands:

git config --global user.name "Your Name Comes Here"
git config --global user.email [email protected]

Branching out

Create a new branch starting from ccase/r13b04_dev (the development branch for the next release). You can do this via the following instructions (assuming you already have a github account and you are signed in):

• Browse to the Erlang/OTP git project page and hit the little ‘fork’ button to create your own fork of the repository (you only have to do this once).
• After the ‘hardcore forking action’ has completed, checkout a copy of your new fork via ‘your’ clone url:
  

  git clone [email protected]:your_username/otp.git

• cd into the new ‘otp’ directory created.
• Create a new remote branch to hold your changes (use a descriptive name for the particular change you’re making):
  

  git push origin origin:refs/heads/new_feature_name

• Start tracking the new branch (this will switch you to the new branch too):
  

  git checkout --track -b new_feature_name origin/new_feature_name

• Pull in all the changes from the ccase/r13b04_dev into your new branch:
  

  git pull origin ccase/r13b04_dev

• Make your changes, commit them according to the guidelines and then send the OTP team a fetch request.

Each branch should contain logically related commits (for example the implementation of a single feature), not a mixed bag of random changes.

Committing the patch

• Make separate commits for separate changes. If you cannot describe what the commit does in one sentence, it is probably a mix of logically separate changes and should be separated into several commits.

• To make it possible to use the powerful git bisect command, make sure that each commit can be compiled and that it works.

• Use the imperative mode in the commit message when describing what you have done: use “change”, “add”, “fix”, not “changed”, “added”, “fixed”. Use the present tense to describe the current implementation: “feature X has an enormous potential for improvements” rather than “feature X had an enormous potential…” (While this writing style may seem awkward to begin with, you’ll find that it is actually easier to read and write.)
  • The first line of the commit message should describe concisely what the commit does. Leave out the full stop. (This line will be visible in gitk or in git log --oneline, so it should be understandable by itself.)
  • The second line in the commit message should be blank.
  • The body of the commit message should primarily answer the question why? rather than how?. That is, the most important is why the change was made, what bug it corrected or why anyone would want to use the new feature it implements. (Imagine yourself five years in the future trying try to figure why anyone would ever want this feature…) Technical details can also be useful, especially why one design was chosen rather than another design (again, imagine yourself investigating a bug and wondering why would anyone chose this way to implement this feature…).
  • Line break the commit message to lines no longer than approximately 70 characters (otherwise they are difficult to read in gitk).

• Do not commit out-commented code or files that are no longer needed.

• Check for unnecessary whitespace before committing with git diff --check.

Making a patch OTP-worthy

The following steps are not necessary if you only want feedback on a proposed change, but are ultimately necessary if you want it to be included in OTP.

• If you are fixing a bug, write a test case before fixing the bug (so that you’ll know that the test case catches the bug). For applications without a test suite in the git repository, it would be appreciated if you provide a small code sample in the commit message or email a module that will provoke the failure.

• If you are implementing a new feature, also write a new test case and/or test_SUITES. (Note: The primary reason for writing test cases is not to prove that the new feature works correctly, but to make sure that it will be noticed if future changes — perhaps to code that seems unrelated — break the feature.)

• If you are implementing a new feature, also update the documentation to describe the feature.

• Make sure that existing test cases don’t fail.

• Make sure that the patch builds and works on all major platforms (many patches we receive works on Linux but not on Windows).

• Make sure that the patch does not break backward compatibility. In general, we only break backward compatibility in major releases and only for a very good reason and usually after first deprecating the feature one or two releases beforehand.

• In general, language changes/extensions or major updates to Kernel and Stdlib also require an EEP (Erlang Enhancement Proposal) to be written and approved before they can be included in OTP.

• Make sure that your changes follow the coding and indentation style of the code surrounding your changes. (At some point in the future, there will be a style guide, either included in the documentation or on some web site, but it is not ready yet.)

• In most code (Erlang and C), indentation is 4 steps using tabs and spaces. Tabs are always 8 steps. (If you use Emacs, use Erlang-mode, and add (setq c-basic-offset 4) to .emacs to get C code correctly indented.)

Sending the patch

Send an email to [email protected] with a reference to your github repository and name of the branch to pull from. To make it really easy for us to fetch the patch, you can include the entire git command. For example:

git fetch git://github.com/bjorng/otp.git my-cool-updates

my-cool-updates is the name of the branch.

Receiving your patch

When we receive your patch, we will do one of the following (typically within a workday):

• If there are simple things that will need to be fixed (for example, providing more information in the commit message instead of in the email), we may ask you to do that.

• Otherwise, if your patch is not obviously wrong or inappropriate, we will merge it to the pu (“proposed updates”) branch, even if it lacks test cases and/or documentation (i.e. it need not be OTP-worthy).

• Otherwise, if it is obviously wrong or inappropriate, we will tell you so. Reasons for immediate rejections include (but are not limited to):
  • Blatantly breaking backward compatibility.
  • Obviously unsafe coding practices or highly non-portable code.
  • Mixing of many difference changes and/or unnecessary re-indentation of code that is not changed. We will ask you to separate the changes into separate commits and/or branches and not change indentation of unchanged code.

You should not base any branches on pu branch, as it will be rebuilt from scratch on top the current development branch frequently.

Currently in the ‘pu’ branch

Testing

We run automatic tests and builds of the pu branch.

If a branch include in pu causes a build problem, that branch will be dropped. We will reinstate the branch if/when we receive a correction.

We might also drop a branch if it causes test case to fail (depending on both the number of failed test cases as well as the kind of failures).

Cooking

Patches will “cook” in the pu branch until they graduate or are dropped.

The following may happen to a patch (one or more times):

• If a patch is not OTP-worthy, it can be replaced with a new or extended version, either by the original author or by someone else.

• If build problems are found on some platform (or there are many failing test cases) not found before it was been included in pu, it may be removed from pu until the problems have been fixed.

• Anyone can criticize, suggest improvements, or report that a patch breaks existing applications. If the serious problems remain, and no good way of fixing them can be found, the patch may be dropped.

• Patches with known issues that have been inactive for a long time will be dropped.

Graduating

Usually a patch will graduate to the release branch for the next release, when it passes the criteria for OTP-worthiness. Usually the maintainer for the application in question will decide when a patch will graduate, but for larger patches and for patches on the borderline of breaking backward compatibility, several people in the OTP group may be involved in the decision.