Skip to content

Latest commit

 

History

History
153 lines (98 loc) · 5.88 KB

CONTRIBUTING.md

File metadata and controls

153 lines (98 loc) · 5.88 KB
Raw

Contributing to Azkaban

👍 First off, thanks for taking the time to contribute! 👍

Please take a moment to read this document if you would like to contribute. Please feel free to reach out on the Azkaban Google Group if you have any questions.

Reporting issues

We use Github issues to track bug reports, feature requests, and submitting pull requests.

If you find a bug:

Use the GitHub issue search to check whether the bug has already been reported. If the issue has been fixed, try to reproduce the issue using the latest master branch of the repository. If the issue still reproduces or has not yet been reported, try to isolate the problem before opening an issue.

Please don't report an issue as a way to ask a question. Use the Google group instead.

Pull requests

Before embarking on making significant changes, please open an issue and ask first so that you do not risk duplicating efforts or spending time working on something that may be out of scope.

Please see the Github documentation for help on how to create a pull request.

Please give your pull request a clear title and description and note which issue(s) your pull request fixes.

Important: By submitting a patch, you agree to allow the project owners to license your work under the Apache 2.0 License.

IDE setup

We recommend IntelliJ IDEA. There is a free community edition available. Azkaban is a standard Gradle project. You can import it into your IDE using the build.gradle file in the root directory. For IntelliJ, choose Open Project from the Quick Start box or choose Open from the File menu and select the root build.gradle file.

Style guides

Azkaban follows the Google code style. The template file, az-intellij-style.xml, can be found in the root directory. It's based on the intellij-java-google-style.xml config file from the google/styleguide project.

Follow the Intellij's code style help to import and set up the style. Make sure to activate the AzkabanStyle by "copy the IDE scheme to the current project, using the Copy to Project... command."

Install and enable the intellij's save actions plugin to reformat/refactor code automatically:

Please turn on all the options except

  • Remove unused suppress warning annotation

It allows us to do following when saving a file:

  • Organize imports
  • Reformat code based on the code style
  • Rearrange code (reorder methods, fields, etc.)
  • Add final to local variable
  • Add final to field
  • Remove explicit generic type for diamond
  • Qualify field access with this
  • Remove final from private method
  • Remove unnecessary semicolon
  • Add missing @Override annotations

New line at the end of a file

Configure Intellij to automatically insert a new line at the end of a file: Preferences → Editor → General → Ensure line feed at file end on Save

todo style

Add your user name to TODO items.

Use the form:

todo username: todo details

Coding conventions

  • Automated tests are expected.

    Exceptions should be rare. An example is automated UI testing, until the test framework catches up.

  • Define configuration keys in the azkaban.Constants class.

  • Favor composition over inheritance.

  • Favor @Singleton notation over the bind method.

    See this example PR.

  • Favor JSR-330's annotations and Provider interface.

    e.g. import javax.inject.Inject; instead of import com.google.inject.Inject;

  • Introduce an interface only when needed.

    When there is a single implementation, don't introduce an interface. When there is a need for a second implementation, refactor the code to introduce an interface as needed. The person making that change in the future will know more (two implementations) than you do now (one implementation) and they will use that knowledge to make better API choices. Modern IDEs have good support for such refactoring. There is less IDE support for removing an interface.

    This convention only applies to the code internal to this project. It's a good use of interfaces for public APIs, which are used by the code that the project owners can't change and evolve easily.

    See this blog post.

  • Favor small and focused classes, files, methods over large ones.

    It's ok to have many classes, files. Here is a rule of 30 suggestion.

  • Use Mockito as the mocking framework in unit tests.

    It's an exception rather than the rule to create custom mocking classes.

  • Use AssertJ as the assertion library in unit tests.

  • Use slf4j instead of log4j.

    Use the form:

    private static final Logger logger = LoggerFactory.getLogger($CLASS_NAME$.class);

  • Add or update the copyright notice for most files.

  • When ignoring a test, provide reasons for ignoring the test.

    Use the form:

    @Ignore("reasons")

Misc