Skip to content

Contributing Guidelines

Build and Test

Prerequisites:

If you are interested in contributing to the UI, the ui folder has a separate README.md.

Script for building the backend, frontend, and spinning up the Docker container all at once: 

./scripts/quick_start_ui.sh

Build the UI in the ui/dist folder and copy the files to the static folder of the UCC. 

./scripts/build_ui.sh

Build a new local version of ucc-gen:

poetry build

Unit tests

poetry run pytest tests/unit

UI tests

If you need to run UI tests for the PR, add a “run-ui-tests” label before the PR is created. UI tests will run automatically for any PR towards the main / develop branches, and on the main / develop branch as well.

  1. With local version of ucc-gen, create a UCCExample add-on for the output directory: 
    poetry run ucc-gen build --source tests/testdata/test_addons/package_global_config_everything/package
  2. Install docker, and run containerized Splunk Enterprise using script: 
    ./scripts/run_splunk.sh
    There are mapped default Splunk ports to host. To use a different configuration, see docker-splunk. Remember to mount the output package to the Splunk apps directory.
  3. Install any browser specific to this browser driver, such as chromedriver for Chrome.
  4. Run tests using the following command: 
    poetry run pytest tests/ui
    Default test parameters use Splunk connection details and credentials from the earlier step, and chromedriver is used as a default webdriver.
    To use a different browser or Splunk configuration, set the proper parameters according to the smartx-ui-test-library documentation.

Linting and Type-checking

ucc-gen uses the pre-commit framework for linting and type-checking. Consult with pre-commit documentation about what is the best way to install the software.

To run it locally:

pre-commit run --all-files

Documentation changes

Documentation changes are also welcome!

To verify changes locally:

poetry run mkdocs serve -a localhost:8001

Issues and bug reports

If you’re seeing some unexpected behavior with ucc-gen, create an issue on GitHub. You can click on “New Issue” and use the template provided.

Pull requests

We love to see pull requests!

We are using conventional commits. The two most important types: “fix” and “feat”, would result in the new version of the ucc-gen once merged.

To do the changes you think are needed, run the previous steps (build / test / linting / documentation). After you create a PR, all the needed reviewers will be added automatically by GitHub.

Gotcha: The semgrep and fossa steps might fail if you are an external contributor. This is expected for now.

Release flow

The instructions below utilize the GitHub CLI tool, which you can install via HomeBrew: 

brew install gh
gh auth login

  • The default development branch is develop. Use this branch for creating pull requests (PRs) for your features, fixes, documentation updates, etc. PRs to the develop branch should be merged using the squash option on GitHub.

  • When it’s time for a release (handled by the UCC team), create a PR from develop to main using the following commands: 

    gh pr create --title "chore: merge develop into main" --body "" --head develop --base main
# set automerge with merge commit to avoid accidentally squashing PR
gh pr merge develop --auto --merge

  • Ensure CI passes and await team review.

  • PR should be merged using merge commit option in GitHub (already included in the command)
  • Releases are made automatically (both on GitHub and PyPI), and a bot will push a commit to main with all necessary changes (i.e. like this)
  • After the release, backport the bot’s changes to the develop branch (i.e. #974):
gh pr create --title "chore: merge main into develop" --body "" --head main --base develop
# set automerge with merge commit to avoid accidentally squashing PR
gh pr merge main --auto --merge
  • If a release encounters issues requiring a quick bug fix (handled by the UCC team):
  • Create a PR to the main branch with the fix, including tests that reproduce and then fix the issue.
  • Ensure CI passes and await team review.
  • Merge the PR using the merge commit option on GitHub.
  • Backport the bug fix PR to the develop branch.