Skip to content

Submitting Patches

Jump to bottom
Bruce Yinhe edited this page May 16, 2016 · 3 revisions

NOTE: This page has been moved to Contribution-Guidelines

Introduction

The recommended way of contributing to Erlang/OTP is described here. Create a new branch and commit your patch, push your changes to your GitHub repository and open a new Pull Request.

Please follow the instructions to help the Erlang/OTP team to be more productive, ultimately benefiting all Erlang/OTP users. You should receive a response within one work day.

Previously the only and standard way to submit your patch was to send it via our erlang-patches mailing list. Subscribe to The mailing list

What will happen with patches submitted via the mailing list?

If you submit a patch in different way from what is described here, it would introduce more work for the Erlang/OTP team. In that case we cannot guarantee anything and it is up to the maintainer for that part of OTP to decide whether they will pick up the patch.

If the patch corrects a bug that the Erlang/OTP team considers severe, 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 handled on a daily basis and your changes will go through essential tests before it is handled and reviewed by the OTP Team.

Please have a look at Using Pull Requests

Bug fix or new feature?

Before you send your patch to us, give it a proper review and consider if it is a bug fix or 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 [email protected]

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 [email protected]: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 [email protected] 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 as a pull request or with appropriate links
  2. The patch is fetched and built by a script
  3. Iff it builds and the commit message passes the check, it is added to our internal system
  4. We receive your patch and it is roughly examined. Time estimation: 1 working day
  5. Your patch is reviewed by the responsible developers.
  6. Tests are run and your patch is examined further. Time estimation: 1-3 working day
  7. 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.

Testing

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

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 for testing, it will be removed 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.

change footers copy tags

Clone this wiki locally