Contributing to Splunk Platform Apps

Thank you for considering spending your time contributing. Whether you're interested in bug-hunting, documentation, or creating entirely new apps, this document will help and guide you through the process.

If you've stumbled upon the site but don't know who or what we are, please check out the links below:

• Splunk!
• Splunk Developer Program
• Info on Splunk Apps and Add-ons

---

First Steps

Make sure you have a GitHub Account

• Make sure you know how Git works.
  • Git Book
  • Git Handbook
  • GitHub Git Guide
  • Git Workflow
  • Git Visualization -> Super cool!

Project Details

To successfully contribute, you should spend a little time familiarizing yourself with the following key topics.

• Coding & Conventions - How we expect to see code formatted and apps named
• Various Types of Apps - Definitions and differences
• Typical developer workflow - Configuring your dev environment

High Level Contribution Overview

Contributing Bug-fixes

If you've found a bug and wish to fix it, the first thing to do is

1. Fork the app repo that you are looking to contribute to.
2. Install pre-commit on your system, if not already installed, and then run pre-commit install while inside the app repo. Note: This step is not required, but strongly recommended! It will allow you to catch issues before even pushing any code.
3. Create a branch.
4. Make your changes on your branch.
5. Thoroughly test your changes. See the Automated Checks section for information about basic automated checks we provide for all apps.
6. Open a pull request to the main branch of the app repo, giving edit access to the maintainers of the repo. Please ensure your pull request adheres to the guidelines mentioned in PULL REQUEST TEMPLATE.

👉 Important Notes 👈

1. Please check the Allow edits and access to secrets by maintainers box during your PR submission so that a developer can aid in the PR process.

2. One issue per branch. We will not accept any Pull Requests that affect more than one App or addresses more than one Issue at a time.

Contributing New Apps

If you've created a brand new App and wish to contribute it, the steps to do so are as follows.

1. Create a new issue in our .github repo to request a new repository to be created for your app.

2. Fork the project.

3. Install pre-commit on your system, if not already installed, and then run pre-commit install while inside the app repo.

   👉 This step is not required, but strongly recommended! It will allow you to catch issues before even pushing any code.

4. Create a branch (following our Conventions).

5. Push your app code to the branch you created.

6. Thoroughly test your code for the new App. See the Automated Checks section for information about basic automated checks we provide for all apps.

7. Perform a pull request to the main branch of the app repo. Please ensure your pull request adheres to the guidelines mentioned in PULL REQUEST TEMPLATE.

Automated Checks

By default we provide various automated checks you can leverage to test your changes automatically. These checks will be run whenever you push new commits to your pull request branch. The overall pass/fail result will appear as a green checkmark or red "x" to the right of commit in the pull request page. To view the detailed report you can do ANY of the following:

• Click the checkmark or "x" and then click the "Details" link. OR
• Click the "Checks" tab at the top of the pull request. OR
• Click the "Details" link next to the list of checks that shows up at the bottom of the pull request. If the tests passed, this list will be hidden, so you will first need to click the "Show all checks" link.

The checks performed are the following:

(Pre-commit checks that can be run with a commit locally or with pre-commit run --all-files)

• Code Quality Checks:
  • Python linting and formatting with Ruff
  • Security scanning with semgrep
  • Shell linting and formatting with ShellCheck
  • (Apps only) Javascript/Typescript linting and formatting with ESLint
• General Checks:
  • Merge conflict detection
  • End-of-file fixing
  • Trailing whitespace cleanup
  • JSON and YAML validation
  • Prevent giant files from being committed
• Splunk-specific Checks:
  • Documentation building
  • App dependency packaging
  • Release notes validation

Additionally, our CI/CD pipeline runs these checks on each pull request:

• Pre-commit Checks:
  • Listed above
• Build: Creates app package
• Sanity Tests: Validates app functionality for the Splunk Cloud environment via AppInspect CLI
• Compatibility Tests: Validates app installation against multiple Splunk distros
• Quality Assessment: Verifies Gold Standard compatibility and checks documentation quality

Other OOB pipelines focus on the documentation deployment and the Add-On release.

Code Release

On each tag push, the following checks will be executed before releasing a new version of the Add-On:

• Build: Creates app package
• Sanity Tests: Validates app functionality for the Splunk Cloud environment via AppInspect CLI
• Compatibility Tests: Validates app installation against multiple Splunk distros
• Release Notes Validation: Checks whether the CHANGELOG.md file has been populated with latest info - guidelines

Code Owners

To ensure code that lives in the repositories is not abandoned, all Splunk Apps and Add-Ons added are required to have a code owner. A code owner is responsible for the Splunk App / Add-On hosted within a repository. This status is identified in the CODEOWNERS file. That responsibility includes maintaining the app, triaging and responding to issues, reviewing pull requests and releasing the app itself as described below.

Requirements

To become a code owner, you will need to have good working knowledge of the code you are sponsoring and any project that that code instruments or is based on.

Responsibilities

As a code owner you will be responsible for the following:

• You will be expected to review any Pull Requests or Issues created that relate to this app.
• You will be responsible for the stability and versioning compliance of the app.
• You will be expected to provide and keep the documentation of the app up to date.
• You will be responsible for releasing new versions of the app.

How to become a Code Owner

Code ownership must be specified when a new repository is requested by opening an Issue.

Multiple code owners can be specified as individual GitHub users.

Removing / Transferring Code Ownership

Code owners are expected to remove their ownership if they cannot fulfill their responsibilities anymore. To do so, open an Issue requesting to either:

• Transfer the code ownership to given user(s),
• Remove the code ownership.

Do not forget to provide the name of the repository the request is referring to.

👉 When a repository has no remaining code owners, the repository will be archived by the organization administrators.

👉 It is at the discretion of the organization administrators to decide if a repository shall be archived in case of inactivity greater than 1 year, during which time there are active Issues or Pull Requests to address.

Dependency Updates

This organization uses Renovate for automated dependency updates. PRs from Renovate are created automatically.

• Review and approve Renovate PRs to trigger auto-merge whenever applicable
• Review, evaluate and manually merge Renovate PRs whenever auto-merge is disabled
• For more details, incl. organization-wide standards, see the CONVENTIONS.md file

Legal Notice

By submitting a Contribution to this Work, You agree that Your Contribution is made subject to the primary license in the Apache 2.0 license (found here). In addition, You represent that: (i) You are the copyright owner of the Contribution or (ii) You have the requisite rights to make the Contribution.

Definitions:

“You” shall mean: (i) yourself if you are making a Contribution on your own behalf; or (ii) your company, if you are making a Contribution on behalf of your company. If you are making a Contribution on behalf of your company, you represent that you have the requisite authority to do so.

"Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You for inclusion in, or documentation of, this project/repository. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication submitted for inclusion in this project/repository, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the maintainers of the project/repository.

“Work” shall mean the collective software, content, and documentation in this project/repository.