guac/CONTRIBUTING.md at Main · Guacsec/Guac  ## Metadata - Author: [[https://github.com/guacsec/]] - Full Title: guac/CONTRIBUTING.md at Main · Guacsec/Guac - Category: #articles - Document Note: --- tags: [ContributingGuidelines, OpenSource, CodeReviews, ContributorLadder, GUACProject] - ContributingGuidelines - OpenSource - CodeReviews - ContributorLadder - GUACProject Author: [GUAC Project Team] Source: [GUAC Contribution Guidelines] Reference: [GitHub - GUAC Documentation] date created: 2024-09-10 --- # Title: How to Contribute to GUAC ## Table of Contents: - [Developer Certificate of Origin](#developer-certificate-of-origin) - [Code Reviews](#code-reviews) - [Community Guidelines](#community-guidelines) - [Getting Started](#getting-started) - [Contributor Ladder](#contributor-ladder) - [Inactivity, Stepping Down](#inactivity-stepping-down) ## 📝 Summary: This guide provides the steps to contribute to the GUAC project, outlining the process for making contributions, the code review process, and the contributor ladder. It includes the necessary guidelines for getting started, understanding community roles, and how to move up the contributor ladder. ## 📖 Main Content: ### Developer Certificate of Origin To contribute, all commits must contain a Signed-off-by line using the `-s` flag in `git commit`. This ensures compliance with the Developer Certificate of Origin (DCO). ### Code Reviews - All submissions, including those by project members, require a code review. - Pull requests must be reviewed by at least two reviewers. - Following CNCF Supply Chain Best Practices ensures security in the project. ### Community Guidelines - Follow the Code of Conduct and maintain a respectful environment. - You can find good starting points by looking for labels like "good first issues" and "help wanted." - Join the Slack channel for questions and discussions. ### Contributor Ladder GUAC contributors progress through various roles: 1. **Community Participant**: Anyone can join, create PRs, comment on issues, etc. 2. **Reviewer**: Review contributions and ensure the PR follows guidelines. 3. **Owner**: Set direction for specific areas of the project. 4. **Maintainer**: Lead the project and participate in decision-making meetings. ### 🗒️ Notes: - Contributors start as **Community Participants** with no special privileges. - **Reviewers** are selected after proving expertise in a topic area and can approve PRs. - **Owners** manage specific project areas and resolve trade-offs. - **Maintainers** set the project's direction and oversee architecture and design. ## 🗣️ Paraphrase: 1. All contributors start as community participants. They can contribute by opening issues, submitting pull requests, and adding comments. As participants show expertise in one of the five areas (Ingestion, API, Backends, Frontend, or Clients), they may be promoted. 2. To be promoted to a reviewer, a community participant must demonstrate their technical proficiency in at least one area. Reviewers are responsible for reviewing contributions in their area and ensuring all contributions adhere to the guidelines. ## 🧪 Hypotheses: - Engaging contributors early and guiding them through the contributor ladder will foster long-term engagement and community growth. - Mandating reviews from multiple experts could reduce bugs and security issues in the codebase. ### 📊 Methodology: To test this, track contributors' activity and retention rates at each ladder level. Use analytics to measure review effectiveness and the impact on code quality. ### ❓ Questions: - How can the project further encourage first-time contributors to remain engaged? - What methods can be introduced to simplify the review process without sacrificing quality? ### 🔮 Future Research: Explore ways to enhance the reviewer and owner role development, potentially with mentorship programs or educational resources to further develop contributors' skills. ### 💡 Implications: Improving the contributor ladder and providing clearer guidance will likely increase the number of long-term contributors. This will strengthen the project by diversifying contributions and reducing the burden on maintainers. ### ✅ Logical Validity: The guidelines focus on clarity and security, ensuring that each contributor understands their role and how to progress. By emphasizing peer reviews and collaboration, the project reinforces trust and quality control. ## 🎯 Conclusion: GUAC's contribution process is designed to be inclusive, structured, and secure. Following these guidelines ensures smooth collaboration and a clear path for contributors to grow within the community. - Document Tags: [[code reviews]] [[contributor guidelines]] [[contributor ladder]] [[open source]] - Summary: The CONTRIBUTING.md document provides guidelines for contributing to the project on GitHub, including setting up and following the Developer Certificate of Origin. Contributors can progress through different roles like Community Participant, Reviewer, Owner, and Maintainer based on expertise and contributions. Active involvement is essential, and inactivity may result in a loss of privileges or voluntary stepping down. - URL: https://github.com/guacsec/guac/blob/main/CONTRIBUTING.md#contributor-ladder [Open in github.dev](https://github.dev/) [Open in a new github.dev tab](https://github.dev/) [Open in codespace](https://github.com/codespaces/new/guacsec/guac/tree/main?resume=1) ### How to Contribute We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow. Refer to the [GraphQL Guide](https://docs.guac.sh/guac-graphql/) to go through a setup. Optionally, you can also consult [docker compose documentation](https://docs.guac.sh/setup/). #### Developer Certificate of Origin We require all commits in a PR 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)](https://wiki.linuxfoundation.org/dco). #### Code Reviews All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests. We also require two reviewers on every PR as this follows good security practices. For reasoning, see [CNCF Supply Chain Best Practices](https://github.com/cncf/tag-security/blob/main/supply-chain-security/supply-chain-security-paper/CNCF_SSCP_v1.pdf). #### Community Guidelines Please refer to the [Code of Conduct](https://github.com/guacsec/guac/blob/main/CODE_OF_CONDUCT.md) for full details. #### Getting Started The project is managed via Github. For contributors that would like to find a good place to start, take a look at the "good first issues" and "help wanted" labels [(filter link here)](https://github.com/guacsec/guac/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22). We also have a [slack channel](https://openssf.slack.com/archives/C03U677QD46) that you can reach us at and ask questions! #### Contributor ladder We are excited that you want to contribute to GUAC! 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 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. The contribution ladder is summarized in the table below: | Role | Responsibilities | Requirements | Privileges | GitHub access level | | --- | --- | --- | --- | --- | | Community Participant | Follow [Google's Open Source Community Guidelines](https://opensource.google/conduct/) | N/A | N/A | Read (default) | | Reviewer | Review contributions from other members | Prove technical expertise in at least one GUAC topic area | Can approve PRs | Write | | 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 | | 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 | 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](https://github.com/guacsec/guac/issues/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 will be promoted to maintainer, after a n-1 approval vote from the other maintainers, according to the processes specified in [the governance document](https://github.com/guacsec/guac/blob/main/GOVERNANCE.md). 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 totalling 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](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 have provided valuable input. The technical advisory members have a consulting role and are the only role without an activity requirement. ##### 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! ##### Reviewers list | Reviewer | Area | Vote | | --- | --- | --- | | [dejanb](https://github.com/dejanb) | Ingestion | [issues/1885](https://github.com/guacsec/guac/issues/1885) | | [mdeicas](https://github.com/mdeicas) | API | [issues/1885](https://github.com/guacsec/guac/issues/1885) | ##### Owners list | Owner | Area | Vote | | --- | --- | --- | | [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) |, guac/CONTRIBUTING.md at Main · Guacsec/Guac, https://github.com/guacsec/, 01hxvt04vnhq2jje1rvqrgnwvc.