By visiting this page, we're going to assume you have an interest in contributing to the Apache Traffic Server project. First, and very importantly, Thank you!

This page will attempt to describe as simply as possible the process by which this project accepts contributions, as well as how the existing project members hope to ideally interact with new contributors to establish and grow relationships with the user and developer communities.

Joining The Community

The core development team, as well as many other contributors and users of Traffic Server, make extensive use of IRC for day to day communication. Joining the #traffic-server channel on Freenode is a great first step. Additionally, you are encouraged to join the users mailing list by sending an email to users-subscribe@trafficserver.apache.org and the developers mailing list by sending an email to dev-subscribe@trafficserver.apache.org.

Finding Things To Work On

The Traffic Server project tracks all open issues, feature requests, bugs, and other tasks in JIRA at https://issues.apache.org/jira/issues/. If you do not already have an improvement in mind, and would rather look for an existing need that is not currently being addressed, browsing through the open and unclaimed issues is highly recommended. Open issues cover functionality or deficiencies already identified by other members of the community, so tackling one of these can be a great introduction.

Submitting Changes

Submissions to the Traffic Server project must follow the contribution process outlined here. At a minimum, all code contributions must:

• Have a JIRA issue, and
• Be submitted as a GitHub pull request.

Patches submitted by any other process, or which do not reference a JIRA issue, will likely be met with a request to follow the steps described below.

Opening A JIRA Issue

Log in, or create an account, at https://issues.apache.org/jira/issues/ and first ensure that there is no existing issue covering your submission. Assuming there is not:

• Click the Create link near the top of the page.
• Ensure that Traffic Server is the project selected.
• Choose an appropriate option for Issue Type, based on the submission you wish to offer.
• Fill out the Summary and Description with as much detail as possible.
• Whenever possible, select the components of Traffic Server which are relevant to the submission.

Before opening new JIRA issues, it is strongly recommended to discuss the feature request, bug fix, etc. on the mailing lists or in IRC. Others in the community may be able to provide insights, suggestions, or alternative approaches to the issue. Working through those first can increase the chances of a successful contribution to the project.

Creating A GitHub Pull Request

Once you have a JIRA issue open, you will need to provide the actual patch(es) for your submission.

Fork Traffic Server

GitHub makes this part easy. While viewing the official Traffic Server repository at https://github.com/apache/trafficserver click the Fork button near the top right of the page. This process may take a moment, but once complete you will have a new project in your personal GitHub account. This is the repository to which you should commit all of your submissions.

Commit Your Changes

Submitting individual changes is most easily done by creating topic branches - a new branch in your fork of the repository specific to the change you wish to submit. Create and checkout your new topic branch before issuing any commits:

$ git checkout -b <topic branch name>

Pushing Your Branch

Your topic branch now needs to be brought up to speed before it can be proposed as a pull request. The first step is to rebase your branch with the current state of the public project, which breaks down into fetching the upstream changes (anything committed to the official repository from which you forked) and then updating your topic branch to incorporate those changes:

$ git checkout master
$ git fetch upstream
$ git merge upstream/master
$ git checkout <topic branch name>
$ git rebase master

If you have any local modifications on your branch, you will need to stash those first, then stash apply them once you have rebased. You may now push your branch to GitHub:

$ git push -u origin <topic branch name>

Create The Pull Request

Once you have pushed your topic branch to your fork, you can generate the GitHub pull request against the official Traffic Server repository. On the GitHub website, browse to your personal fork of the project. Select the topic branch which you just pushed, and click on the New Pull Request link next to the branch. The base should be the official Traffic Server repository (on its master branch) and the head should be your personal fork (on the appropriate topic branch).

Pull requests should always reference the JIRA issue to which the changes are related. Convention is to list the JIRA issue at the very beginning of the pull request title, followed by a very brief (a few dozen characters or less) description of the PR. A pull request referencing JIRA issue #123, for example, might be titled "TS-123: frobnicates the wobblinar using whosi-whatsits." A more detailed explanation of the pull request's contents should be included in the description body.

Once all these have been filled out, you're ready to click Create Pull Request.

Discuss, Modify, Rinse, Repeat

Once your pull request has been opened, committers and other community members with the Traffic Server project may comment with suggestions, alternatives, advice, and proposed tweaks or changes. This process may repeat through a few rounds as your submission is refined. Once your pull request has reached a point where the committers have accepted it, one of them will merge the request into the official repository and your contribution will become an official part of the public project. Congratulations!