How to Contribute
We'd love to get patches from you!
We are not currently publishing snapshots for Finagle's dependencies, which
means that it may be necessary to publish the
develop branches of these
libraries locally in order to work on Finagle's
develop branch. To do so
you can use our build tool, dodo.
curl -s https://raw.githubusercontent.com/twitter/dodo/develop/bin/build | bash -s -- --no-test finagle
The workflow that we support:
- Fork finagle
- Check out the
- Make a feature branch (use
git checkout -b "cool-new-feature")
- Make your cool new feature or bugfix on your branch
- Write a test for your change
- From your branch, make a pull request against
- Work with repo maintainers to get your change reviewed
- Wait for your change to be pulled into
twitter/finagle/developinto your origin
- Delete your feature branch
There are a number of things we like to see in pull requests. Depending on the scope of your change, there may not be many to take care of, but please scan this list and see which apply. It's okay if something is missed; the maintainers will help out during code review.
- Include tests.
- Update the changelog for new features, API breakages, runtime behavior changes, deprecations, and bug fixes.
- New metrics should be documented in the user guide.
- All public APIs should have Scaladoc.
- When adding a constructor to an existing class or arguments to an existing method, in order to preserve backwards compatibility for Java users, avoid Scala's default arguments. Instead use explicit forwarding methods.
- The second argument of an
@deprecatedannotation should be the current date, in
We've standardized on using the ScalaTest testing framework.
Because ScalaTest has such a big surface area, we use a restricted subset of it
in our tests to keep them easy to read. We've chosen the
assert API, not the
Matchers one, and we use the
FunSuite mixin, which supports
We encourage our contributors to ensure Java compatibility for any new public APIs
they introduce. The easiest way to do so is to provide Java compilation tests
and make sure the new API is easily accessible (typing
X$.MODULE$ is not easy)
from Java. These compilation tests also provide Java users with testable examples
of the API usage. For an example of a Java compilation test see
Note that while you will see a Travis CI status message in your pull request, this may not always be accurate, and in any case all changes will be tested internally at Twitter before being merged. We're working to make Travis CI more useful for development, but for now you don't need to worry if it's failing (assuming that you are able to build and test your changes locally).
When appropriate, use ScalaCheck to write property-based tests for your code. This will often produce more thorough and effective inputs for your tests. We use ScalaTest's GeneratorDrivenPropertyChecks as the entry point for writing these tests.
We try to keep public APIs stable for the obvious reasons. Often, compatibility can be kept by adding a forwarding method. Note that we avoid adding default arguments because this is not a compatible change for our Java users. However, when the benefits outweigh the costs, we are willing to break APIs. The break should be noted in the Breaking API Changes section of the changelog. Note that changes to non-public APIs will not be called out in the changelog.
While the project is written in Scala, its public APIs should be usable from
Java. This occasionally works out naturally from the Scala interop, but more
often than not, if care is not taken Java users will have rough corners
SomeCompanion$.MODULE$.someMethod() or a symbolic operator).
We take a variety of approaches to minimize this.
- Add a "compilation" unit test, written in Java, that verifies the APIs are usable from Java.
- If there is anything gnarly, we add Java adapters either by adding a non-symbolic method name or by adding a class that does forwarding.
traitsas they are easier for Java developers to extend.
When creating an issue please try to ahere to the following format:
module-name: One line summary of the issue (less than 72 characters) ### Expected behavior As concisely as possible, describe the expected behavior. ### Actual behavior As concisely as possible, describe the observed behavior. ### Steps to reproduce the behavior List all relevant steps to reproduce the observed behavior.
Comments should be formatted to a width no greater than 80 columns.
Files should be exempt of trailing spaces.
We adhere to a specific format for commit messages. Please write your commit
messages along these guidelines. Please keep the line width no greater than
80 columns (You can use
fmt -n -p -w 80 to accomplish this).
module-name: One line description of your change (less than 72 characters) Problem Explain the context and why you're making that change. What is the problem you're trying to solve? In some cases there is not a problem and this can be thought of being the motivation for your change. Solution Describe the modifications you've done. Result What will change as a result of your pull request? Note that sometimes this section is unnecessary because it is self-explanatory based on the solution.
The Finagle repository on GitHub is kept in sync with an internal repository at Twitter. For the most part this process should be transparent to Finagle users, but it does have some implications for how pull requests are merged into the codebase.
When you submit a pull request on GitHub, it will be reviewed by the Finagle community (both inside and outside of Twitter), and once the changes are approved, your commits will be brought into the internal system for additional testing. Once the changes are merged internally, they will be pushed back to GitHub with the next release.
This process means that the pull request will not be merged in the usual way. Instead a member of the Finagle team will post a message in the pull request thread when your changes have made their way back to GitHub, and the pull request will be closed (see this pull request for an example). The changes in the pull request will be collapsed into a single commit, but the authorship metadata will be preserved.
Please let us know if you have any questions about this process!
We've created a
Starter label for issues that we think are likely to be
reasonably limited in scope and ready to be tackled by new contributors. Please
feel free to ask questions in the issue thread or on the mailing list if
you run into problems trying to implement a new feature or fix a bug described
in one of the starter issues.
We also welcome improvements to the Finagle documentation, which is maintained in this repository and hosted on the corresponding GitHub Pages site.
Once you've got Sphinx installed, you can make changes to the RST files in
doc/src/sphinx directory and then build the site with the following
command from the
./sbt 'project finagle-doc' makeSite
You can then view the site locally at
Please note that sbt-site currently will not work with the Python 3 version of
Sphinx. It's also hard-coded to call an executable named
on some systems may be the name of the Python 3 version, with the Python 2
sphinx-build2. If the site build process crashes with a "Failed
to build Sphinx html documentation", this is likely to be the problem. The
simplest solution is to create a symbolic link to
sphinx-build somewhere on your path.
Please note that any additions or changes to the API must be thoroughly described in Scaladoc comments. We will also happily consider pull requests that improve the existing Scaladocs!