Page History

As an open source project, Metron welcomes contributions of all forms. The sections below will help you get started.

1. How To Contribute

We are always very happy to have contributions, whether for trivial cleanups, little additions or big new features.

If you don't know Java or Scala you can still contribute to the project. We strongly value documentation and gladly accept improvements to the documentation.

1.1  Contributing A Code Change

To submit a change for inclusion, please do the following:

• If there is not already a JIRA associated with your pull request, create it, assign it to yourself, and start progress
• If there is a JIRA already created for your change then assign it to yourself and start progress
• If you don't have access to JIRA or can't assign an issue to yourself, please message dev@metron.incubator.apache.org and someone will either give you permission or assign a JIRA to you
• If you are introducing a completely new feature or API it is a good idea to start a discussion and get consensus on the basic design first.  Larger changes should be discussed on the dev boards before submission.
• New features and significant bug fixes should be documented in the JIRA and appropriate architecture diagrams should be attached.  Major features may require a vote.
• Note that if the change is related to user-facing protocols / interface / configs, etc, you need to make the corresponding change on the documentation as well.
• Craft a pull request following the guidelines in Section 2 of this document
• Pull requests should be small to facilitate easier review. Studies have shown that review quality falls off as patch size grows. Sometimes this will result in many small PRs to land a single large feature.
• People will review and comment on your pull request.  It is our job to follow up on pull requests in a timely fashion.
• Once the pull request is merged , the person doing the merge (committer) should manually close the corresponding JIRA.

1.2 Reviewing and merging patches

Everyone is encouraged to review open pull requests. We only ask that you try and think carefully, ask questions and are excellent to one another. Code review is our opportunity to share knowledge, design ideas and make friends.

When reviewing a patch try to keep each of these concepts in mind:

2.6  Merge requirements

Because Metron is so complex, and the implications of getting it wrong so devastating, Metron has a strict merge policy for committers:

• Patches must never be pushed directly to master, all changes (even the most trivial typo fixes!) must be submitted as a pull request.
• A committer may merge their own pull request, but only after a second reviewer has given it a +1. A qualified reviewer is a Metron committer or PPMC member.
• A non-committer may ask the reviewer to merge their pull request or alternatively post to the Metron dev board to get another committer to merge the PR if the reviewer is not available. 
• There should be at least one independent party besides the committer that have reviewed the patch before merge.
• A patch that breaks tests, or introduces regressions by changing or removing existing tests should not be merged. Tests must always be passing on master. This implies that the tests have been run.
• All pull request submitters must link to travis-ci 
• If somehow the tests get into a failing state on master (such as by a backwards incompatible release of a dependency) no pull requests may be merged until this is rectified.
• All merged patches will be reviewed with the expectation that automated tests exist and are consistent with project testing methodology and practices, and cover the appropriate cases ( see reviewers guide )
  
  

The purpose of these policies is to minimize the chances we merge a change that jeopardizes has unintended consequences.