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:

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.  The instructions on how to checkout a patch for review can be found here

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



Also, please review if the submitter correctly flagged impacts to the following (if exist):


2.  Implementation


2.1  Grammar and style

These are small things that are not caught by the automated style checkers.

2.2  Code Style

2.2.1 IntelliJ IDEA Checkstyle Warnings

New, Checkstyle-based, warnings should show up in Java files, e.g.

Checkstyle: WhitespaceAround: 'if' is not followed by whitespace. Empty blocks may only be represented as {} when not part of a multi-block statement

2.2.2 IntelliJ IDEA Code Formatting

  • Download https://github.com/google/styleguide/blob/gh-pages/intellij-java-google-style.xml
  • In IDEA, go to Preferences -> Editor -> Code Style.
  • Click in the Settings gear next to the Scheme selection box.  Go to Import Scheme -> IntelliJ IDEA Code Style XML
  • Choose the previously downloaded XML file.
  • It's also possible to import the Checkstyle file directly (instead of Import Scheme -> IntelliJ IDEA Code Style XML use Import Scheme -> Checkstyle Configuration). In practice, the Google IntelliJ IDEA settings appear to be more complete.

2.2.3. Eclipse Checkstyle Warnings

2.2.4 Eclipse Code Formatting

2.3  Coding Standards

2.4 Documentation

2.4.1 Creating and Modifying Diagrams Using draw.io

All steps expect the source and derived image files will be committed to source control via Git.

Creating and Exporting Diagrams as Images

  1. Open your diagram in draw.io
  2. Select "File → Export as → PNG..." (you can use other formats as well, e.g. SVG)
  3. If using PNG, you can leave the defaults and click "Export." If you want the background transparent, select that option before exporting.
  4. Name your file accordingly and choose "Download."
  5. Place the downloaded file in "<module-name>/images" as noted in the "Diagrams" section under 2.4.0 above. 

Exporting Source Files for Diagrams

  1. Open your diagram in draw.io
  2. Select "File → Export as → XML..."
  3. Enable the checkbox for "Compressed" and click "Export"
  4. Name your file accordingly and choose "Download."
  5. Open the file you downloaded. Remove the xml header (<?xml version="1.0" encoding="UTF-8"?>), and add the following license header at the top of the file.
  6. <!--
    Licensed to the Apache Software
    Foundation (ASF) under one or more contributor license agreements. See the
    NOTICE file distributed with this work for additional information regarding
    copyright ownership. The ASF licenses this file to You under the Apache License,
    Version 2.0 (the "License"); you may not use this file except in compliance
    with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
    Unless required by applicable law or agreed to in writing, software distributed
    under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
    OR CONDITIONS OF ANY KIND, either express or implied. See the License for
    the specific language governing permissions and limitations under the License.
    -->
    <!-- This is a draw.io diagram source file. You can edit it on http://www.draw.io -->
  7. Save the changes and place them in the relevant Maven project module under "<module-name>/images-source" as noted in the "Diagrams" section under 2.4.0 above.

Modifying Existing Diagrams

  1. Navigate to draw.io
  2. Select "Open Existing Diagram" from the prompt.
  3. Click "Upload" and click "Select a file from your device" and choose the diagram you want to edit.
  4. The file should be open for editing now.
  5. Make any desired changes and export the source XML files and new images as described above.

2.5  Tests

 

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:

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

2.6.1 Inactive Pull Requests

Contributions can often take a significant amount of time to complete the code review process. This process requires active participation from the contributor. If the contributor is unable to actively participate, the pull request is unlikely to successfully complete this process.

Pull Requests that have failed to receive active participation from the contributor for an extended period of time risk being abandoned. Any committer can submit a request for Apache Infra to close a pull request that has been abandoned according to the following guidelines.


3.  JIRA