Skip to content

.github.md

Latest commit

 

History

History
273 lines (192 loc) · 10.1 KB

.github.md

File metadata and controls

273 lines (192 loc) · 10.1 KB
Raw

Falco .github Repository Digest

Source: refs/falcosecurity/.github/ Era: 0.44 Last Updated: 2026-02-03

Overview

The falcosecurity/.github repository contains the default community health files for the entire falcosecurity GitHub organization. These files provide organization-wide defaults for contributing guidelines, security policy, code of conduct, and issue templates.

Scope: Special (per evolution/repositories.yaml)

Note: This repository contains policies that apply across all falcosecurity repositories. Individual repositories may override these defaults with their own files.

Repository Structure

File Purpose
CONTRIBUTING.md Contribution guidelines
SECURITY.md Security vulnerability reporting
CODE_OF_CONDUCT.md Code of conduct (mirrors evolution)
GOVERNANCE.md Redirect to evolution
contributing/review-process.md Code review process
.github/ISSUE_TEMPLATE/ Default issue templates

Contributing Guidelines

Source: CONTRIBUTING.md

Code of Conduct

All contributors must adhere to the CNCF Code of Conduct.

Contact for issues:

Community Channels

Channel Purpose
Slack #falco Support requests, discussions
Mailing list News, announcements
Community calls Weekly discussions (Wed 4 PM UTC)
HackMD agenda Add topics for calls

Poiana Bot

All falcosecurity repositories use @poiana bot for governance, workflow, and triaging.

Common commands:

/area <area>           # Add area label
/kind <kind>           # Add kind label (mandatory for issues)
/label <label>         # Add custom label
/remove-<type> <name>  # Remove label
/cc @username          # Suggest reviewer
/assign @username      # Assign to user
/lgtm                  # Mark as "looks good to me"
/approve               # Approve PR (maintainers only)

Issue Types

Type Template Label
Bug report bug_report.md kind/bug
Feature request feature_request.md kind/feature
Failing tests failing_tests.md -
Documentation docs_request.md -

Required: A kind/* label is mandatory for any issue.

Bug Report Template

When reporting bugs, include:

  • Falco version (falco --version)
  • System info (falco --support | jq .system_info)
  • Cloud provider or hardware
  • OS (cat /etc/os-release)
  • Kernel (uname -a)
  • Installation method (Kubernetes, RPM, DEB, source)

Pull Request Process

  1. Submit PR with appropriate labels (/area, /kind)
  2. Automation suggests reviewers from OWNERS files
  3. Review by maintainers/reviewers
  4. LGTM - Reviewer types /lgtm if code looks good
  5. Approve - Maintainer uses GitHub "Approve" review
  6. Auto-merge when all conditions met

Merge conditions:

  • Required labels present (lgtm, approved)
  • No blocking labels (do-not-merge/*, needs-rebase)
  • All required GitHub checks passing
  • Sufficient approving reviews

Note: Some repositories (notably falco and libs) require two or more maintainer approvals.

Rebasing (Conflict Resolution)

Always use git rebase (not merge) to resolve conflicts:

# Setup
git checkout -b my-feature-branch
git remote add upstream <upstream_url>
git fetch upstream

# Rebase
git rebase --signoff -i upstream/main

# Resolve conflicts
git add <conflicting-file>
git rebase --continue

# Push
git push --force-with-lease

Important: Use --force-with-lease instead of --force to prevent overwriting others' changes.

Commit Convention

Falco follows Conventional Commits v1.0.0:

Prefix Usage
fix: Patching a bug
feat: or new: Introducing a new feature
! after type or BREAKING CHANGE: in footer Breaking change

Some repositories require a release-note block following the same convention.

Developer Certificate of Origin (DCO)

All commits must be signed off:

git commit -s -m "Your commit message"

Format:

This is my commit message

Signed-off-by: Name <email@example.com>

The @poiana bot enforces DCO on all PRs.

Licensing Guidelines

Code Review Process

Source: contributing/review-process.md

For Code Authors

First-time contributors:

  • Study project history, workflow, and style
  • Start with small patches
  • Ask for help and feedback early
  • Work in the open

Best practices:

  • Meet all preconditions (testing, explanations)
  • Divide large PRs into smaller ones
  • Expect first-pass review within ~1 week
  • Check status weekly if no response
  • Be responsive to reviewer comments

For Code Reviewers

  • Maintain respectful tone
  • Assume competence and positive intentions
  • Be mindful of diverse backgrounds
  • Consider continuous review (benefits everyone)
  • Explain reasoning behind change requests
  • Help with testing significant patches
  • Avoid excessive personal style preferences

Review Timeline

  • First-pass review: ~1 week
  • Milestone assignment: PR will be merged before release freeze if possible
  • Escalation: Reach out to core maintainers during community calls if issues arise

Security Policy

Source: SECURITY.md

Reporting Vulnerabilities

Email: cncf-falco-maintainers@lists.cncf.io

Include "SECURITY" in the subject line.

Process

  1. Initial response indicates next steps
  2. Progress updates provided
  3. May request additional information
  4. Disclosure via GitHub Security Advisories

Supported Versions

Security updates typically only applied to the latest release (until Falco 1.0 stable).

Repository Ownership

Source: OWNERS

Role Members
Approvers leogr, maxgio92, jasondellaluce, LucaGuerra
Emeritus leodido, fntlnz, kris-nova, mfdii

Contributor Recognition

Contributor of the Month

Outstanding contributors recognized monthly.

See: Falco Contributor Hall of Fame

Becoming a Maintainer

Process documented in MAINTAINERS_GUIDELINES.md.

Cross-References

This repository provides defaults; detailed governance lives in other repositories:

Document Location
Governance evolution/GOVERNANCE.md
Full Code of Conduct evolution/CODE_OF_CONDUCT.md
Maintainers Guidelines evolution/MAINTAINERS_GUIDELINES.md
Maintainers List evolution/MAINTAINERS.md
Repository Guidelines evolution/REPOSITORIES.md
Community community/

Sources

Topic Source File
Contributing guidelines CONTRIBUTING.md
Code review process contributing/review-process.md
Security policy SECURITY.md
Code of conduct CODE_OF_CONDUCT.md
Repository ownership OWNERS
Bug report template .github/ISSUE_TEMPLATE/bug_report.md
Feature request template .github/ISSUE_TEMPLATE/feature_request.md
Governance (evolution) evolution/GOVERNANCE.md
Maintainers guidelines evolution/MAINTAINERS_GUIDELINES.md

Version History

Date Changes
2026-02-03 Initial digest creation