Contributing to GUAC

Interested in making a contribution to GUAC? This is the place to start! Here are a few things you need to know.

If you’re looking for an issue to get started on, check the “good first issue” and “help wanted” tags in GitHub.

Code of Conduct

GUAC is an OpenSSF Incubating Project. The OpenSSF Code of Conduct applies to all interactions in the GUAC community.

Developer Certificate of Origin

We require all commits in a pull request to contain a Signed-off-by line which can be added by using the -s flag of git commit. This is to enforce a Developer Certificate of Origin (DCO).

Contributor ladder

This contributor ladder outlines different contributor roles within the project, along with responsibilities and privileges that come with them.

Since GUAC is a complex project, there are 5 software topic areas of interest:

• Ingestion: ingest software security metadata. Needs to write parsers for documents, maintain ingestion logic, write new collectors, etc.
• API: define the GraphQL/REST interface used between ingestion pipeline and backend, and between backend and GUAC-based applications and front-ends.
• Backends: define efficient code to interface with database backends (Neo4j, etc.).
• Front-end: GUAC visualisation libraries, Javascript, CSS
• Clients: GUAC CLI, CI Checks, Policy Engines, IDE Plugins, etc.

In addition, there are 2 non-code topic areas:

• Documentation: Maintaining docs and examples
  • Repositories:
    • guacsec/guac-docs
    • guacsec/guac-data
• Web and marketing: Maintain GUAC’s public presence
  • Repositories:
    • guacsec/guac-landing
    • (eventual social media accounts)

The contribution ladder is summarized in the table below. All software and non-code topic areas use this latter.

Ladder levels

Each level of the ladder is also described in more details below.

Community Participant

Each new contributor to GUAC starts at this level. There is no longer a formal requirement to register desire to contribute in issue #1.

There are no requirements and no privileges. Every community participant can create issues, fork the repository, create PRs, add comments to issues and PRs.

Reviewer

Once a community participant has demonstrated expertise in one GUAC topic area, owners and/or maintainers can propose graduating the community participant to the Reviewer role, upon a maintainer majority vote.

A reviewer will be responsible of reviewing contributions from other contributors that touch the corresponding topic area. They should ensure that the PRs are adequately tested, follow the guidelines for the specific topic area.

Owner

A reviewer with significant review history and proven record of authorship in a specific GUAC topic area can be promoted to Owner status, upon a maintainer majority vote.

The Owner is in full control over the specific topic area. They are expected to set direction and priorities, resolve technical trade-offs, prioritize between adding new features and handling technical debt. As such, they must show a deep understanding of technical problems involved in this area.

Owners are invited to the GUAC owners and maintainers Slack channel.

Owners will be added to CODEOWNERS file, so they will be notified of PRs that touch their area of interest.

Maintainer

An owner that gains a deep understanding of GUAC architecture and design and can prove this by being an OWNER in at least 3 topic areas (including both software and non-code topic areas) will be promoted to maintainer, after a n-1 approval vote from the other maintainers, according to the processes specified in the governance document.

A maintainer has almost full access to the repository and is invited to all maintainer meetings, where they can contribute input that will set direction and priorities of the entire project. They must have ability to commit to participating to at least the weekly maintainer sync meetings (currently 2 meetings totaling up to 2 hours every week).

A maintainer might be required to work with GUAC clients, thus they might be required to sign NDAs.

The GUAC governance document also details the role of technical advisory member, which is offered to members of the community that have provided valuable input. The technical advisory members have a consulting role and are the only role without an activity requirement.

Moving up and down the ladder

To request being moved up the ladder, or to step down voluntarily, file an issue in the governance repo.

Promotion

If you are requesting promotion, please include links to significant contributions in support of your request. See governance#15 as an example. The requirements for each level are given in the preceding sections.

Inactivity, Stepping down

Each role in the contribution ladder requires maintaining active contributions at the corresponding level. Inactivity is harmful to the project, so maintainers can decide to remove privileges from inactive contributors, after a majority vote. Inactivity is defined as periods longer than 3 months during which no contribution is being done.

Contributors also have the option of stepping down voluntarily, by contacting the maintainers when circumstances affect future contribution potential. For highly active contributors that completely step away from the project, we will create an emeritus process.

GUAC contributors are happy to help you advance along the contributor ladder!

Contacts

Reviewers list

Owners list

Maintainers

See the MAINTAINERS file for a list of current maintainers.