The following provides instructions on how to set up your dev environment so you can start contributing to the Apache Metron project quickly.
The below instructions is with the IntelliJ as the IDE. However, you can use whatever IDE you would like to contribute to Metron.
- Create an account on Githhub if you don't already have an account.
- Download the latest version of IntelliJ
Setting up your Dev Env
The below provides instructions on how to setup your Dev environment with Github and IntelliJ
Fork the Metron Repo
We need to first fork the Apache Metron repo. Forking a repository allows you to freely experiment with changes without affecting the original project. See here for details on forking.
The below provides instructions on how to fork the Metron Repo:
- Log into your github account
- Go to https://github.com/apache/incubator-metron and click the Fork button and fork into your github account.
- You should now have a fork like: https://github.com/[github_user_name]/incubator-metron
Clone the Metron repo to you local Dev Env
After forking, clone the repo to your local dev workstation. See following instructions:
- Start IntelliJ
- Click File --> New --> Project from Version Control --> Github
- Configure the Github Repo URL that you forked earlier to clone.
Setup your Cloned Repo as an IntelliJ project
- After the project has has been setup, you should see a prompt to add the cloned repo as a maven project. Click the "Add as Maven Project"
- Setup the Java SDK as 1.8 (if you don't have oracle jdk 1.8, please install it first)
- File -> Project Structure --> Project Settings --> Project --> Select 1.8 as SDK
- Setup the Project Structure correctly
- Go to File --> Project Structure --> Project Settings --> Module
- select plus sign and select "Import Module"
- Go to the location where you cloned your fork on your local workstation and select the metron-streaming folder
- Check the checkbox "Import module as from External Folder" and Select Maven
- Leave the default setting on the import settings page
- Click Finish
- you should see something like the following:
- Do steps b - g for the following folders under the cloned repo directory: deployment, metron-sensors, metron-ui and site
- Build the entire project and ensure that you have no errors: Build --> Make Project
How to Start Contributing
Now that you have setup your IDE environemnt and want to contribute on an enhancement, do the the following:
Create a JIRA Ticket
- Create JIRA ticket in Metron JIRA for the enhancement that you want to work on if it doesn't exist.
- Do your work within your Intellij project
Committing your changes to your Local Repo
After you have completd a small unit of work for the enhancement, you want to commit the changes to your lcoal repo. Do the following
- Go to version control tab --> local changes --> right on the files that you modified or created --> select commit changes
- Confirm the commit by adding the commit message and the JIRA numebr associated with the commit.
Pushing the Local Committed Changes to the Forked Github repo
Now that the changes have been committed to local repo. We want to push and commit those changes to your forked github.
- Right Click on on the project in IntelliJ --> Git --> Repository --> Push
- Click Push
- You should now see the changes in the forked repo on your github account
Create a Pull Request
Pull requests let you tell others about changes you've pushed to a GitHub repository. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.
- Log into your github account and go to your forked repo.
- Click the button "new pull request"
- Please be very careful to preface your PR with the full name of the JIRA so that the comments from github are replicated to the JIRA system for posterity. The name must be exact. If there is a JIRA, METRON-777, that is titled "Fix all the things!", please create your PR with the title: "METRON-777: Fix all the things!"
- Please fill out the PR template completely. For code submissions it will ask you not only to run full Unit Test, but also the integration test module, via
mvn -q clean integration-test install && build_utils/verify_licenses.sh