Skip to content

Latest commit

 

History

History
68 lines (43 loc) · 6.06 KB

CONTRIBUTING.md

File metadata and controls

68 lines (43 loc) · 6.06 KB
Raw

Content Contribution Guide

Content logo

Welcome to Demisto content repo! Contributions are welcome and appreciated.

How to contribute

Please read the following guidelines. Following these guidelines will maximize the chances for a fast, easy and effective review process for everyone involved. If something is not clear, please don't hesitate to reach out to us via GitHub, Slack, or email.

  • Setup a development environment by following the Dev Setup Guide.
  • Use the Package Directory Structure for all Python code. If working on existing code, beyond trivial changes, we require converting to this structure as it allows running linting, unit tests and provides a clearer review process.
  • Make sure to read and follow code conventions.
  • Run and verify that the various linters we support pass as detailed here.
  • For Scripts/Integrations written in Python, make sure to create unit tests as documented here
  • Create a test playbook as documented here. Note: for simple Scripts that have unit tests, a test playbook is optional.
  • Validate that our validation hooks pass. If you used .hooks/bootstrap as documented in the Dev Setup Guide the validation hook will run automatically upon commit. You can also run the validation hooks manually by running .hooks/pre-commit.
  • Document your integration as detailed here.
  • Document your changes in the relevant changelog file as detailed here.

You should now be ready to create a pull request.

Create a Pull Request on GitHub

If you are a first time GitHub contributor, please look at these links explaining on how to create a Pull Request to a GitHub repo:

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub

Review Process

Once you open a pull request we have a bot (@content-bot) that will assist you and provide comments and reminders about the state of the pull request. Additionally, a member of the team will be assigned to review the pull request. Comments will be provided by the team member as the review process progresses.

You will see a few GitHub Status Checks that help validate that your pull request is according to our standards:

  • ci/circleci: build: We use CircleCI to run a full build on each commit of your pull request. The build will run our content validation hooks, linting and unit test. We require that the build pass (green build). If it is failing our content-bot will also add instructive comments about what sections are failing in the build. Follow the details link of the status to see the full build UI of CircleCI. More details about our build flow of CircleCI is available here.
  • demisto/pull-check: Status check that validates that included documentation and release notes are approved. Once the documentation has been reviewed and approved, this status check will pass.
  • LGTM analysis: Python: We use LGMT for continues code analysis. If your PR introduces new LGTM alerts, the LGTM bot will add a comment with links for more details. Usually, these alerts are valid and you should try to fix them. If the alert is a false positive, specify this in a comment of the PR.
  • guardrails/scan: We use Guardrails for continuous security feedback. If the alert generated by Guardrails is a false positive, specify this in a comment of the PR.
  • license/cla: Status check that all contributors have signed our contributor license agreement (see below).

Contributor License Agreement

Before merging any PRs, we need all contributors to sign a contributor license agreement. By signing a contributor license agreement, we ensure that the community is free to use your contributions.

When you contribute a new pull request, a bot will evaluate whether you have signed the CLA. If required, the bot will comment on the pull request, including a link to accept the agreement. The CLA document is available for review as a PDF.

If the license/cla status check remains on Pending, even though all contributors have accepted the CLA, you can recheck the CLA status by visiting the following link (replace [PRID] with the ID of your PR): https://cla-assistant.io/check/demisto/content?pullRequest=[PRID] .

Pull updates from Demisto Content base branch

When you open a PR, as a first step our @content-bot will change the base branch of your pull request to a new branch named: contrib/<username>_<your branch name>.

In general, there shouldn't be a reason for you to pull changes from the base branch into your forked branch.

In case it is needed, you shouldn't pull from the master branch, but from the Demisto Content branch the Pull Request in based on.

In order to pull changes from the base branch, run:

git pull https://github.com/demisto/content.git <DEMISTO-CONTENT-BASE-BRANCH>

For example, if the base branch name is contrib/itay_master, you should run:

git pull https://github.com/demisto/content.git contrib/itay_master

If you have a suggestion or an opportunity for improvement that you've identified, please feel free to open a PR.

Enjoy and feel free to reach out to us on the DFIR Community Slack channel or at [email protected].