Contributor Guide

Thank you for your interest in contributing to Pepr! We welcome all contributions and are grateful for your help. This guide outlines how to get started with contributing to this project.

Table of Contents

• Contributor Guide
  • Table of Contents
  • Code of Conduct
  • Getting Started
    • Setup
    • Kubernetes Fluent Client Contributions
  • Submitting a Pull Request
    • PR Requirements
  • Coding Guidelines
    • Git Hooks
  • Running Tests
    • Run Tests Locally
    • Test a Local Development Version
  • Contact

Code of Conduct

Please follow our Code of Conduct to maintain a respectful and collaborative environment.

Getting Started

• Repository: https://github.com/defenseunicorns/pepr/
• npm package: https://www.npmjs.com/package/pepr
• Required Node version: >=20.0.0

Setup

1. Fork the repository.
2. Clone your fork locally: git clone https://github.com/your-username/pepr.git.
3. Install dependencies: npm ci.
4. Create a new branch for your feature or fix: git checkout -b my-feature-branch.

Kubernetes Fluent Client Contributions

Kubernetes Fluent Client is a library used by Pepr that provides a fluent interface for Kubernetes API clients. In Pepr, we use the kubernetes-fluent-client package to interact with Kubernetes resources. Due to the nature of this library, it is important to ensure that any changes made to the Kubernetes Fluent Client are thoroughly tested and validated in Pepr before being merged into the codebase. In particular, we need to ensure that the changes do not break any existing functionality or introduce new bugs, especially in the context of the Pepr Watcher.

If you are making changes to the Kubernetes Fluent Client, please ensure that you run the Soak Test in GitHub Actions to validate your changes.

To run the Soak Test, you can do the following:

• Go to the GitHub Actions tab
• Select the workflow named “Soak Test”
• Click on the “Run workflow” button to get the options to run the workflow
• Select the Kubernetes Fluent Client branch you want to test (KFC dev branch) and click “Run workflow”

Submitting a Pull Request

1. Create an Issue: For significant changes, please create an issue first, describing the problem or feature proposal. Trivial fixes do not require an issue.
2. Commit Your Changes: Make your changes and commit them. All commits must be signed.
3. Run Tests: Ensure that your changes pass all tests by running npm test.
4. Push Your Branch: Push your branch to your fork on GitHub.
5. Create a Pull Request: Open a pull request against the main branch of the Pepr repository. Please make sure that your PR passes all CI checks.

PR Requirements

• PRs must be against the main branch.
• PRs must pass CI checks.
• All commits must be signed.
• PRs should have a related issue, except for trivial fixes.

We take PR reviews seriously and strive to provide a great contributor experience with timely feedback. To help maintain this, we ask external contributors to limit themselves to no more than two open PRs at a time. Having too many open PRs can slow down the review process and impact the quality of feedback

Coding Guidelines

Please follow the coding conventions and style used in the project. Use ESLint and Prettier for linting and formatting:

• Check formatting: npm run format:check
• Fix formatting: npm run format:fix
• If regex is used, provide a link to regex101.com with an explanation of the regex pattern.
• Do not use emoji in logs or comments, as it can be distracting and is not consistent with the project’s style.

Git Hooks

• This project uses husky to manage git hooks for pre-commit and pre-push actions.
• pre-commit will automatically run linters so that you don’t need to remember to run npm run format:* commands
• pre-push will warn you if you’ve changed lots of lines on a branch and encourage you to optionally present the changes as several smaller PRs to facilitate easier PR reviews.
  • The pre-push hook is an opinionated way of working, and is therefore optional.
  • You can opt-in to using the pre-push hook by setting PEPR_HOOK_OPT_IN=1 as an environment variable.

Automated Workflows

Grype Suppression Audit

A weekly GitHub Actions workflow (grype-suppression-audit.yaml) scans the Pepr controller image for stale CVE suppressions in .grype.yaml. When stale entries are found, the workflow removes them and opens (or updates) a PR on the bot-owned branch grype/suppression-audit.

• Do not push manual commits to grype/suppression-audit — the workflow force-pushes to this branch weekly and any manual changes will be overwritten.
• To add context to a suppression entry (e.g. reason:), add it directly to .grype.yaml on main. The audit script skips multi-key entries and will not remove them automatically.

Peer-Dependency Updates

The peerDependencies block in package.json is maintained by the peer-deps-update GitHub Actions workflow. The workflow runs every Monday and opens PRs grouped by SemVer risk: a single PR for all minor/patch bumps and a separate PR per major-version bump (so that majors get isolated review and revert paths).

• To trigger an off-cycle run, dispatch the workflow manually from the Actions tab.
• To inspect the latest peer-dep candidates locally without opening a PR, run node scripts/update-peer-deps.mjs report.
• To apply bumps locally, run node scripts/update-peer-deps.mjs apply --kind minor for the minor/patch group or node scripts/update-peer-deps.mjs apply --kind major --pkg <name> for a single major bump.

Dependabot continues to handle the dependencies and devDependencies blocks; the two automations never touch the same region of package.json.

Running Tests

Run Tests Locally

• Run all tests: npm test

Test a Local Development Version

1. Run npm test and wait for completion.
2. Change to the test module directory: cd pepr-test-module.
3. You can now run any of the npx pepr commands.

Running Development Version Locally

1. Run npm run build to build the package.
2. For running modified pepr, you have two options:
   1. Using npx ts-node ./src/cli.ts init to run the modified code directly, without installing it locally. You’ll need to also run npx link <your_dev_pepr_location> inside your pepr module, to link to the development version of pepr.
   2. Install the pre-build package with npm install pepr-0.0.0-development.tgz. You’ll need to re-run the installation after every build, though.
3. Run npx pepr dev inside your module’s directory to run the modified version of pepr.

Tip

Make sure to re-run npm run build after you modify any of the pepr source files.

Contact

For any questions or concerns, please open an issue on GitHub or contact the maintainers.