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 on Github. 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.

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!

  • No labels