|
| 1 | +--- |
| 2 | +title: "Contributing to GUAC" |
| 3 | +section: single |
| 4 | +type: page |
| 5 | +include_footer: true |
| 6 | +--- |
| 7 | + |
| 8 | +Interested in making a contribution to GUAC? |
| 9 | +This is the place to start! |
| 10 | +Here are a few things you need to know. |
| 11 | + |
| 12 | +If you're looking for an issue to get started on, check the ["good first issue"](https://github.com/search?q=user%3Aguacsec+label%3A%22good+first+issue%22++&type=Issues&ref=advsearch&l=&l=&state=open) and ["help wanted"](https://github.com/search?q=user%3Aguacsec+label%3A%22help+wanted%22++&type=Issues&ref=advsearch&l=&l=&state=open) tags in GitHub. |
| 13 | + |
| 14 | +## Code of Conduct |
| 15 | + |
| 16 | +GUAC is an OpenSSF Incubating Project. |
| 17 | +The [OpenSSF Code of Conduct](https://openssf.org/community/code-of-conduct/) applies to all interactions in the GUAC community. |
| 18 | + |
| 19 | +## Developer Certificate of Origin |
| 20 | + |
| 21 | +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`. |
| 22 | +This is to enforce [a Developer Certificate of Origin (DCO)](https://wiki.linuxfoundation.org/dco). |
| 23 | + |
| 24 | +## Contributor ladder |
| 25 | + |
| 26 | +This contributor ladder outlines different contributor roles within the project, along with |
| 27 | +responsibilities and privileges that come with them. |
| 28 | + |
| 29 | +Since GUAC is a complex project, there are 5 software topic areas of interest: |
| 30 | + |
| 31 | +- Ingestion: ingest software security metadata. Needs to write parsers for |
| 32 | + documents, maintain ingestion logic, write new collectors, etc. |
| 33 | +- API: define the GraphQL/REST interface used between ingestion pipeline and |
| 34 | + backend, and between backend and GUAC-based applications and front-ends. |
| 35 | +- Backends: define efficient code to interface with database backends (Neo4j, |
| 36 | + etc.). |
| 37 | +- Front-end: GUAC visualisation libraries, Javascript, CSS |
| 38 | +- Clients: GUAC CLI, CI Checks, Policy Engines, IDE Plugins, etc. |
| 39 | + |
| 40 | +In addition, there are 2 non-code topic areas: |
| 41 | + |
| 42 | +- Documentation: Maintaining docs and examples |
| 43 | + - Repositories: |
| 44 | + - guacsec/guac-docs |
| 45 | +- Web and marketing: Maintain GUAC’s public presence |
| 46 | + - Repositories: |
| 47 | + - guacsec/guac-landing |
| 48 | + - (eventual social media accounts) |
| 49 | + |
| 50 | +The contribution ladder is summarized in the table below. |
| 51 | +All software and non-code topic areas use this latter. |
| 52 | + |
| 53 | +| Role | Responsibilities | Requirements | Privileges | GitHub access level |
| 54 | +| ---- | ---------------- | ------------ | ---------- | ------------------- |
| 55 | +| [Community Participant](#community-participant) | Follow [OpenSSF Code of Conduct](https://openssf.org/community/code-of-conduct/) | N/A | N/A | Read (default) |
| 56 | +| [Reviewer](#reviewer) | Review contributions from other members | Prove technical expertise in at least one GUAC topic area | Can approve PRs | Write |
| 57 | +| [Owner](#owner) | Set direction and priorities for topic area. Approval of contributions | Deep technical expertise in topic area. Proven record of reviews and authorship. | Invitation to owner&maintainers only channels | Write |
| 58 | +| [Maintainer](#maintainer) | Set direction and priorities of project. Participate in weekly syncs | Expertise in 3 out of the 5 topic areas | (almost) complete repository access | Maintain |
| 59 | + |
| 60 | +### Ladder levels |
| 61 | + |
| 62 | +Each level of the ladder is also described in more details below. |
| 63 | + |
| 64 | +#### Community Participant |
| 65 | + |
| 66 | +Each new contributor to GUAC starts at this level. |
| 67 | +There is no longer a formal requirement to |
| 68 | +[register desire to contribute in issue #1](https://github.com/guacsec/guac/issues/1). |
| 69 | + |
| 70 | +There are no requirements and no privileges. |
| 71 | +Every community participant can create issues, fork the repository, create PRs, add comments to issues and PRs. |
| 72 | + |
| 73 | +#### Reviewer |
| 74 | + |
| 75 | +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. |
| 76 | + |
| 77 | +A reviewer will be responsible of reviewing contributions from other contributors that touch the corresponding topic area. |
| 78 | +They should ensure that the PRs are adequately tested, follow the guidelines for the specific topic area. |
| 79 | + |
| 80 | +#### Owner |
| 81 | + |
| 82 | +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. |
| 83 | + |
| 84 | +The Owner is in full control over the specific topic area. |
| 85 | +They are expected to set direction and priorities, resolve technical trade-offs, prioritize between adding new features and handling technical debt. |
| 86 | +As such, they must show a deep understanding of technical problems involved in this area. |
| 87 | + |
| 88 | +Owners are invited to the GUAC owners and maintainers Slack channel. |
| 89 | + |
| 90 | +Owners will be added to `CODEOWNERS` file, so they will be notified of PRs that touch their area of interest. |
| 91 | + |
| 92 | +#### Maintainer |
| 93 | + |
| 94 | +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 |
| 95 | +the processes specified in [the governance document](https://github.com/guacsec/guac/blob/main/GOVERNANCE.md). |
| 96 | + |
| 97 | +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. |
| 98 | +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). |
| 99 | + |
| 100 | +A maintainer might be required to work with GUAC clients, thus they might be required to sign NDAs. |
| 101 | + |
| 102 | +The [GUAC governance document](https://github.com/guacsec/guac/blob/main/GOVERNANCE.md) also details the role of technical advisory member, which is offered to members of the community that |
| 103 | +have provided valuable input. |
| 104 | +The technical advisory members have a consulting role and are the only role without an activity requirement. |
| 105 | + |
| 106 | +### Moving up and down the ladder |
| 107 | + |
| 108 | +To request being moved up the ladder, or to step down voluntarily, file an issue in the [governance repo](https://github.com/guacsec/governance). |
| 109 | + |
| 110 | +#### Promotion |
| 111 | + |
| 112 | +If you are requesting promotion, please include links to significant contributions in support of your request. |
| 113 | +See [governance#15](https://github.com/guacsec/governance/issues/15) as an example. |
| 114 | +The requirements for each level are given in the preceding sections. |
| 115 | + |
| 116 | +#### Inactivity, Stepping down |
| 117 | + |
| 118 | +Each role in the contribution ladder requires maintaining active contributions at the corresponding level. |
| 119 | +Inactivity is harmful to the project, so maintainers can decide to remove privileges from inactive contributors, after a majority vote. |
| 120 | +Inactivity is defined as periods longer than 3 months during which no contribution is being done. |
| 121 | + |
| 122 | +Contributors also have the option of stepping down voluntarily, by contacting the maintainers when circumstances affect future contribution potential. |
| 123 | +For highly active contributors that completely step away from the project, we will create an emeritus process. |
| 124 | + |
| 125 | +GUAC contributors are happy to help you advance along the contributor ladder! |
| 126 | + |
| 127 | + |
| 128 | +## Contacts |
| 129 | + |
| 130 | +### Reviewers list |
| 131 | + |
| 132 | +| Reviewer | Area | Vote | |
| 133 | +|-|-|-| |
| 134 | +| [dejanb](https://github.com/dejanb) | Ingestion | [issues/1885](https://github.com/guacsec/guac/issues/1885) | |
| 135 | +| [mdeicas](https://github.com/mdeicas) | API | [issues/1885](https://github.com/guacsec/guac/issues/1885) | |
| 136 | + |
| 137 | + |
| 138 | +### Owners list |
| 139 | + |
| 140 | +| Owner | Area | Vote | |
| 141 | +|-|-|-| |
| 142 | +| [mrizzi](https://github.com/mrizzi) | [Backends (ent)](https://github.com/guacsec/guac/tree/4012842fab5d738f9bebf03f0cb44fc7ce39438b/pkg/assembler/backends/ent) | [issues/1310](https://github.com/guacsec/guac/issues/1310) | |
| 143 | + |
| 144 | + |
| 145 | +### Maintainers |
| 146 | + |
| 147 | +See the [MAINTAINERS file](https://github.com/guacsec/guac/blob/main/MAINTAINERS) for a list of current maintainers. |
0 commit comments