Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Introduction

The standard way and historically the only way is to submit your patch via our erlang-patches Mailing List.
Make sure you subscribe to The mailing list

The recommended way of sending patches is described on this page. First, you push your changes to a git repository and send us an email with a reference to your public git repository and branch. If mailing is not your cup of tea, you may send us a Pull Request via GitHub.

If you follow the instructions, you should receive a response within one workday.

By following the instructions, you help the Erlang/OTP team to be more productive, ultimately benefiting all Erlang/OTP users.

What will happen with patches sent as attachments?

If you submit a patch in a way other than what is described here, it implies more work for the Erlang/OTP team. In that case we cannot guarantee anything. It is up to the maintainer for that part of OTP to decide whether (s)he will pick up the patch.

If the patch corrects a bug considered severe by the Erlang/OTP team we will take care of it regardless of how it was submitted. This includes bugs related to system startup, corrupt data and bugs causing VM crashes. We never apply patches without verification, and may implement the patch in a way we find better than the original patch.

What about pull requests?

Pull requests are now handled on a daily basis and your changes will go through essential tests before it will be handled and reviewed by the OTP Team.

If you are not used to GitHub Pull Requests, please have a look at Using Pull Requests to familiarize yourself with the concept.

Bug-fix or new feature?

Before you send your patch to us, take a deep thought about your contribution, whether it is a bug-fix or if it is a new feature. If it is a new feature, you will need to provide us further information and the process is slightly longer.
If your patch is not a new feature you can stop reading now and skip to next point.
If you patch is a new feature you need to make a EEP Light in about 200 words and put this in the mail that you will send to us. The time-estimation for receiving an answer of interest in this new feature is approximately one month.

Setting up user information

Please have git setup with consistent user information before sending a patch. Preferably with your real name and a
working email address (the one you use on the erlang-patches mailing list, for example).
For quick reference, here are the relevant git commands:

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com

Branching out

To ease our daily testings, we want all patches based on the maint branch. After review, you may get questioned to rebase your patch on master if we think that your new feature will end up in that branch.

So, create a new branch starting from maint (the maintenance branch for the current major 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 ‘fork’ button to create your own fork of the repository (you only have to do this once).
  • After the ‘hardcore forking action’ has completed, check out a copy of your new fork via ‘your’ clone URL:
    git clone git@github.com:your_username/otp.git
  • cd into the newly created ‘otp’ directory
  • Create a remote pointing to the OTP repository.
    git remote add upstream git://github.com/erlang/otp.git
  • Create a new remote branch to hold your changes (use a descriptive name for the particular change you are 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 master and/or maint branch on the otp remote into your new branch:
    git pull upstream master
  • Make your changes, commit them according to the guidelines and then send the OTP team a fetch request.
  • If it takes you a while to finish your changes or you need some update from a newer master than you branched from, rebase your branch on master. After checking out your branch:
    git fetch upstream
    git rebase upstream/master
    … And fix any merge conflicts. Do not merge from master since we want a straight chain of commits based on a fairly recent master.
  • If you create a patch based on someone else’s patch you can do exactly that: branch from someone else’s branch (that branches from a fairly recent master).

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

See forking tips on GitHub, for managing the OTP team branches as the upstreams.

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 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.
  • Do not commit commented-out code or files that are no longer needed.
  • Check for unnecessary whitespace before committing with git diff --check.

Making a patch OTP-compliant

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.

  • Make sure existing test cases do not fail.
  • Make sure the patch builds and works on all major platforms (many patches we receive work on Linux but not on Windows).
  • Make sure 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.)

Base your branch on maint

  • If you are fixing a bug, write a test case before fixing the bug (so that you will 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.

Base your branch on master

  • 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 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.

Sending the patch

Send an email to erlang-patches@erlang.org with a reference to your github repository and name of the branch to pull from (and the EEP Light document if it is a new feature). To make it really easy for us to fetch the patch, please 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.

Additionally include the following two links for viewing the changes:

https://github.com/mygithub/otp/compare/erlang:BASE...my-cool-updates
https://github.com/mygithub/otp/compare/erlang:BASE...my-cool-updates.patch

And last but not least create a pull request for the patch.

All this will make sure that we can handle your patch as fast as possible, by getting some automatic building/testing on the patch before we take a look ourselves.

where BASE should be the base branch, maint or master.

For the diff to be correct you need to make sure that the default branch configured on github is set to maint or master (which is the case when you fork) and is up-to-date (same as upstream/BRANCH).

(We also accept inline patches compatible with format generated by git format-patch, but please make sure your email client has not garbled the message.)

Receiving your patch

Irrespective if your patch is a new feature or a bug-fix, you will get a confirmation mail within 1-3 working days.

If your patch is a new feature, this is what is going to happen:

  1. You are sending your patch to us (with the Erlang/OTP EEP Light document).
  2. We receive your patch and send a confirmation mail that we have received your patch. Time estimation: 1 working day
  3. After we first receive your feature patch proposal you will get an acknowledgement within a couple of days that it has been received. After that the patch will be reviewed by a an OTP developer. In this review process the feature will be triaged. It may take some time to run through our queue but we aim at having a triage answer within 3-4 weeks:
    1. Green light – Feature patch proposal is sound and the proposed design looks good.
      This is a wanted feature and has good design – Great but still might need some work meaning:
      • Failing test cases
      • Lacking documentation
      • Lacking support for some platforms (Windows)
    2. Yellow light – Feature patch proposal is sound but proposed design is flawed or uncertain.
      This is a wanted feature but the design is either flawed or has semantic changes.
      This also means that your feature proposal will not be accepted as is.
      One of two things will happen:
      • Your proposal needs additional review by OTP Technical board and this will take additional time.
        The ball is in OTP’s courtyard.
      • Your proposal needs a different approach and we explain why your current approach will not work.
        The ball is in your courtyard.
    3. Red light – Feature patch proposal is rejected.
      In some cases and for various reasons a proposal will be rejected.
      • The feature has too severe impact on the system
      • Adds too much complexity
      • Compatibility changes
      • or any other changes we deem problematic or unwanted.
  4. Tests are run and your patch is examined further. Time estimation: 1 working day
  5. Your patch is reviewed by the responsible developers. Time estimation: 1-3 working days
  6. If and only if the outcome of testing and building your patch with Erlang/OTP is positive your patch is merged to the appropriate master or maint branch.

If your patch is a bug-fix, this is what is going to happen:

  1. You are sending your patch to us (with appropriate links)
  2. We receive your patch and it is roughly examined. Time estimation: 1 working day
  3. Your patch is merged to the appropriate ‘pu’ branch
  4. Tests are run and your patch is examined further. Time estimation: 1 working day
  5. Your patch is reviewed by the responsible developers. Time estimation: 1-3 working days
  6. If and only if the outcome of testing and building your patch with Erlang/OTP is positive your patch is merged to the appropriate master or maint branch.
  • Otherwise, if the patch 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 different 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 a pu branch, as it will frequently be rebuilt from scratch on top of the current development branch.

Currently in the ‘pu’ branch

Testing

We run automatic tests and builds of the pu branch.

If a branch included 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 cases to fail.

We might also drop a branch if we want to address the issue in a different way.

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-compliant, 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 included in pu, it may be removed from pu until the problems have been corrected.
  • Anyone can criticise, suggest improvements, or report that a patch breaks existing applications. If the serious problems remain, and no good way of correcting 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 maint or master branch when it passes the criteria for being OTP-compliant. Application-maintainer in question will decide when a patch will graduate. For larger patches and for patches on the borderline of breaking backward compatibility, several people in the OTP group will be involved in the graduation process.

Something went wrong with that request. Please try again.