Commit 3c7df2db authored by Michelle Nguyen's avatar Michelle Nguyen
Browse files

Add governance and contributing docs

Summary: tsia

Test Plan: n/a

Reviewers: zasgar, vihang

Reviewed By: zasgar

Differential Revision: https://phab.corp.pixielabs.ai/D8257

GitOrigin-RevId: 3dadc88a3c8b17ae74006478509aea4d319a4374
parent 9a688dbc
main snyk-fix-7eb526f73c75336b865418bda117e40b snyk-fix-a916784efb9d8870d42eeba63409bf85 release/vizier/vv0.9.8-pre-test.27 release/vizier/v0.11.7 release/vizier/v0.11.6 release/vizier/v0.11.5 release/vizier/v0.11.4 release/vizier/v0.11.3 release/vizier/v0.11.2 release/vizier/v0.11.1 release/vizier/v0.11.0 release/vizier/v0.10.22 release/vizier/v0.10.21 release/vizier/v0.10.20 release/vizier/v0.10.19 release/vizier/v0.10.18 release/vizier/v0.10.17 release/vizier/v0.10.16 release/vizier/v0.10.15 release/vizier/v0.10.14 release/vizier/v0.10.13 release/vizier/v0.10.12 release/vizier/v0.10.11 release/vizier/v0.10.10 release/vizier/v0.10.9 release/vizier/v0.10.8 release/vizier/v0.10.7 release/vizier/v0.10.6 release/vizier/v0.10.5 release/vizier/v0.10.4 release/vizier/v0.10.3 release/vizier/v0.10.2 release/vizier/v0.10.1 release/vizier/v0.10.0 release/vizier/v0.9.16 release/vizier/v0.9.14 release/vizier/v0.9.14-pre-main.5 release/vizier/v0.9.13 release/vizier/v0.9.13-pre-r0.17 release/vizier/v0.9.12 release/vizier/v0.9.12-pre-r0.1 release/vizier/v0.9.11 release/vizier/v0.9.11-pre-r0.32 release/vizier/v0.9.11-pre-r0.29 release/vizier/v0.9.11-pre-main.9 release/vizier/v0.9.8 release/vizier/v0.9.8-pre-test.27 release/vizier/v0.9.8-pre-test2.28 release/vizier/v0.9.7 release/vizier/v0.9.7-pre-r0.7 release/vizier/v0.9.7-pre-main.27 release/vizier/v0.9.6 release/vizier/v0.9.5 release/vizier/v0.9.5-pre-r0.13 release/vizier/v0.9.5-pre-main.18 release/vizier/v0.9.5-pre-main.17 release/vizier/v0.9.5-pre-main.14 release/vizier/v0.9.5-pre-etcdConfig.15 release/vizier/v0.9.4 release/vizier/v0.9.3 release/vizier/v0.9.2 release/vizier/v0.9.1 release/vizier/v0.9.0 release/vizier/v0.8.10 release/vizier/v0.8.9 release/vizier/v0.8.8 release/vizier/v0.8.7 release/vizier/v0.8.6 release/vizier/v0.8.5 release/vizier/v0.8.3 release/vizier/v0.8.2 release/vizier/v0.8.1 release/vizier/v0.8.0 release/vizier/v0.7.19 release/vizier/v0.7.18 release/vizier/v0.7.17 release/vizier/v0.7.16 release/vizier/v0.7.15 release/vizier/v0.7.14 release/vizier/v0.7.13 release/vizier/v0.7.12 release/vizier/v0.7.11 release/vizier/v0.7.10 release/vizier/v0.7.9 release/vizier/v0.7.8 release/vizier/v0.7.7 release/vizier/v0.7.6 release/vizier/v0.7.5 release/vizier/v0.7.4 release/vizier/v0.7.3 release/vizier/v0.7.2 release/vizier/v0.7.1 release/operator/v0.0.30 release/operator/v0.0.29 release/operator/v0.0.28 release/operator/v0.0.27 release/operator/v0.0.26 release/operator/v0.0.25 release/operator/v0.0.24 release/operator/v0.0.23 release/operator/v0.0.22 release/operator/v0.0.21 release/operator/v0.0.20 release/operator/v0.0.19 release/operator/v0.0.18 release/operator/v0.0.17 release/operator/v0.0.16 release/operator/v0.0.15 release/operator/v0.0.15-pre-r0.6 release/operator/v0.0.14 release/operator/v0.0.14-pre-zOperator3.8 release/operator/v0.0.14-pre-r0.8 release/operator/v0.0.13 release/operator/v0.0.13-pre-test.5 release/operator/v0.0.13-pre-main.5 release/operator/v0.0.12 release/operator/v0.0.12-pre-main.6 release/operator/v0.0.11 release/operator/v0.0.10 release/operator/v0.0.9 release/operator/v0.0.7 release/operator/v0.0.5 release/operator/v0.0.2 release/cloud/staging/1637355758 release/cloud/staging/1637266321 release/cloud/staging/1637083942 release/cloud/staging/1636658412 release/cloud/staging/1636655115 release/cloud/staging/1636566009 release/cloud/staging/1636486580 release/cloud/staging/1635273164 release/cloud/staging/1634664761 release/cloud/staging/1634662582 release/cloud/staging/1634426539 release/cloud/staging/1634255213 release/cloud/staging/1633889214 release/cloud/staging/1633467640 release/cloud/staging/1633377421 release/cloud/staging/1632931048 release/cloud/staging/1632880554 release/cloud/staging/1631813710 release/cloud/staging/1631205641 release/cloud/prod/1658198111 release/cloud/prod/1658185818 release/cloud/prod/1658183222 release/cloud/prod/1657740688 release/cloud/prod/1657049209 release/cloud/prod/1656629056 release/cloud/prod/1656527373 release/cloud/prod/1656452950 release/cloud/prod/1655997138 release/cloud/prod/1655226092 release/cloud/prod/1654806360 release/cloud/prod/1654144074 release/cloud/prod/1654133791 release/cloud/prod/1652313416 release/cloud/prod/1652304483 release/cloud/prod/1652214656 release/cloud/prod/1651864223 release/cloud/prod/1651799821 release/cloud/prod/1651704659 release/cloud/prod/1651616922 release/cloud/prod/1650645384 release/cloud/prod/1650480744 release/cloud/prod/1650306041 release/cloud/prod/1650056868 release/cloud/prod/1650039340 release/cloud/prod/1649978499 release/cloud/prod/1649797942 release/cloud/prod/1649787581 release/cloud/prod/1649269698 release/cloud/prod/1649107437 release/cloud/prod/1648586238 release/cloud/prod/1647992139 release/cloud/prod/1647379907 release/cloud/prod/1646182041 release/cloud/prod/1644961014 release/cloud/prod/1644348245 release/cloud/prod/1643849214 release/cloud/prod/1643826488 release/cloud/prod/1643153852 release/cloud/prod/1643056106 release/cloud/prod/1643052598 release/cloud/prod/1642705917 release/cloud/prod/1642632551 release/cloud/prod/1642205277 release/cloud/prod/1642145141 release/cloud/prod/1642141551 release/cloud/prod/1642139120 release/cloud/prod/1642134238 release/cloud/prod/1642130337 release/cloud/prod/1642126826 release/cloud/prod/1642124521 release/cloud/prod/1642109235 release/cloud/prod/1641941995 release/cloud/prod/1641420513 release/cloud/prod/1641254216 release/cloud/prod/1638917470 release/cloud/prod/1637096190 release/cloud/prod/1636492829 release/cloud/prod/1635286066 release/cloud/prod/1634668183 release/cloud/prod/1634663695 release/cloud/prod/1634282223 release/cloud/prod/1633893408 release/cloud/prod/1633710125 release/cloud/prod/1633560085 release/cloud/prod/1633495949 release/cloud/prod/1633474704 release/cloud/prod/1633379527 release/cloud/prod/1632935904 release/cloud/prod/1631826310 release/cloud/prod/1630737620 release/cloud/prod/1630714187 release/cloud/prod/1630622583 release/cloud/prod/1630433362 release/cloud/prod/1630110767 release/cloud/prod/1629952882 release/cloud/prod/1629920564 release/cloud/prod/1629851112 release/cloud/prod/1629494063 release/cloud/prod/1629339917 release/cloud/prod/1629337848 release/cloud/prod/1629335332 release/cloud/prod/1629311730 release/cloud/prod/1629166688 release/cloud/prod/1629166023 release/cloud/prod/1629165964 release/cloud/prod/1629151138 release/cloud/prod/1628025334 release/cloud/prod/1627971857 release/cloud/prod/1627943140 release/cloud/prod/1627935195 release/cloud/prod/1627644793 release/cloud/prod/1627601637 release/cloud/prod/1627445520 release/cloud/prod/1627421364 release/cloud/prod/1626909202 release/cloud/prod/1626824610 release/cloud/prod/1626391194 release/cloud/prod/1626321970 release/cloud/prod/1626073778 release/cloud/prod/1625699466 release/cloud/prod/1625253333 release/cloud/prod/1625249910 release/cloud/prod/1625013333 release/cloud/prod/1625003953 release/cloud/prod/1625001388 release/cloud/prod/1624993505 release/cloud/prod/1624989299 release/cloud/prod/1623456844 release/cloud/prod/1622779032 release/cloud/prod/1621989349 release/cloud/prod/1621986389 release/cloud/prod/1621964672 release/cloud/prod/1621920686 release/cloud/prod/1621917276 release/cloud/prod/1621882022 release/cloud/prod/1620958944 release/cloud/prod/1620945558 release/cloud/prod/1620327546 release/cloud/prod/1620273211 release/cloud/prod/1620271073 release/cloud/prod/1620090826 release/cloud/prod/1619828773 release/cloud/prod/1619741770 release/cloud/prod/1619126029 release/cli/v0.7.16 release/cli/v0.7.15 release/cli/v0.7.14 release/cli/v0.7.13 release/cli/v0.7.12 release/cli/v0.7.11 release/cli/v0.7.10 release/cli/v0.7.9 release/cli/v0.7.8 release/cli/v0.7.7 release/cli/v0.7.6 release/cli/v0.7.5 release/cli/v0.7.4 release/cli/v0.7.3 release/cli/v0.7.2 release/cli/v0.7.1 release/cli/v0.7.1-pre-r0.5 release/cli/v0.7.0 release/cli/v0.7.0-pre-main.11 release/cli/v0.6.8-pre-main.9 release/cli/v0.6.7 release/cli/v0.6.6 release/cli/v0.6.5 release/cli/v0.6.4 release/cli/v0.6.3 release/cli/v0.6.2 release/cli/v0.6.1 release/cli/v0.5.14 release/cli/v0.5.13 release/cli/v0.5.12 release/cli/v0.5.11 release/cli/v0.5.9 release/cli/v0.5.8 release/cli/v0.5.7 release/cli/v0.5.6 release/cli/v0.5.5 release/cli/v0.5.4 release/cli/v0.5.3 release/cli/v0.5.2 release/cli/v0.5.1
No related merge requests found
Showing with 193 additions and 0 deletions
+193 -0
# Contributing Guidelines
Pixie welcomes contributions from the community. This document outlines the conventions that should be followed when making a contribution.
## Contact Us
For any questions regarding Pixie or the contribution process, feel free to reach out to us:
- Email: community@pixielabs.ai
- Slack: [slackin.withpixie.ai](slackin.withpixie.ai)
## Where to start?
You can contribute to Pixie in many ways. This includes, but is not limited to:
- Bug and feature reports
- Documentation
- Development of features and bug fixes
If you are interested in helping us shape our community, you can also [apply here](https://pixielabs.ai/community/) to be a Pixienaut.
## Contribution Process
### Reporting Bugs and Creating Issues
Reporting bugs is one of the most helpful ways to contribute to Pixie. Bugs may be reported by filing a Github issue in the appropriate repository. For bugs regarding Pixie, file an issue in the `pixie` repo. For reporting inaccurate documentation, file an issue in the `pixie-docs` repo, etc. Please follow the template when filing an issue and provide as much information as possible.
Before reporting a bug, we encourage you to search the existing Github issues to ensure that the bug has not already been filed.
### Code Contributions
The project is still in its early stages, and we are a small team actively working on delivering our roadmap. For all changes, regardless of size, please create a Github issue that details the bug or feature being addressed before submitting a pull request. In the Github issue, contributors may discuss the viability of the solution, alternatives, and considerations.
#### Contribution Roadmap
As we are still an early-stage open source project, more changes to the contribution guidelines will follow in the coming months. We are actively working on opening our JIRA for issue tracking.
#### Contribution Flow
1. Steps to making a code contribution to Pixie will generally look like the following:
2. Fork the repository on Github.
3. Create a new branch.
4. Make your changes in organized commits.
5. Push your branch to your fork.
6. Submit a pull request to the original repository.
7. Make any changes as requested by the maintainers.
8. Once accepted by a maintainer, it will be merged into the original repository by a maintainer.
#### Contribution Checklist
When making a contribution to the repository, please ensure that the following is addressed.
1. Code follows Pixie’s coding style guide.
2. All existing tests must pass, and new tests must be added for the bug/feature in question.
3. Contributor License agreement must be signed.
#### Coding Style
Please refer to the style guide directory for more details.
#### Commit Messages
Commit messages should provide enough information about what has changed and why. Please follow the templates for how this information should be detailed.
#### CLA
All code contributions require the [Contributor License Agreement](https://github.com/pixie-labs/pixie/blob/main/CLA.md). The CLA can be signed when creating your first PR.
# The Project
Pixie (The Project) is an open source software project. The goal of The Project is to develop open source software and enable out-of-the-box visibility into developer’s Kubernetes applications. The Software developed by The Project is released under the Apache 2.0 license and is developed openly and hosted in public Github/Phabricator Repositories under the PixieLabs organization. Examples of Project Software include the Pixie core library, Pixie Python API, Pixie Go API, and Pixie documentation.
The Project is developed by a distributed team of developers, called Contributors. Contributors are individuals who have contributed code, documentation, designs, user support, or other work to one or more Project repositories. Anyone can be a Contributor. Contributors can be affiliated with any legal entity or none. Contributors participate in the project by submitting, reviewing and discussing Code Contributions and Issues and participating in open and public Project discussions on GitHub, JIRA, Phabricator, Slack, and mailing lists. The foundations of Project participation are openness and transparency.
[Here](https://github.com/pixie-labs/pixie/blob/main/AUTHORS) is a list of some code Contributors to the main Pixie repository.
The Project Community consists of all Contributors and Users of the Project. Contributors work on behalf of and are responsible to the larger Project Community and we strive to keep the barrier between Contributors and Users as low as possible.
# Governance
This section describes the governance and leadership model of The Project.
The foundations of Project governance are:
- Openness & Transparency
- Active Contribution
- Institutional Neutrality
The following structure will remain in place until May 2023, at which point at the sole discretion of the BDFL we will revisit the structure. The proposed future structure is a semi-democratic process for selecting project leadership.
## BDFL
The Project will have a BDFL (Benevolent Dictator for Life), who is currently Zain Asgar, and a Deputy BDFL, who is Michelle Nguyen. As Dictator, the BDFL has the authority to make all final decisions for The Project. As Benevolent, the BDFL, in practice chooses to defer that authority to the consensus of the community discussion channels and the Governance Board (see below). It is expected, and in the past has been the case, that the BDFL will only rarely assert their final authority. Because rarely used, we refer to BDFL’s final authority as a “special” or “overriding” vote. When it does occur, the BDFL override typically happens in situations where there is a deadlock in the Governance Board or if the Governance Board asks the BDFL to make a decision on a specific matter. The BDFL is chair of the Governance Board (see below) and may delegate their authority on a particular decision or set of decisions to any other Board member at their discretion.
## Governance Board
The project will have a governance board that consists of two project members, two community members, and two end-user community members. The overall role of the Board is to ensure, working with the BDFLs and taking input from the Community, a long-term well-being of the project, both technically and as a community.
The Governance Board and its Members play a special role in certain situations. In particular, the Board may:
- Make decisions about the overall scope, vision and direction of the project.
- Make decisions about strategic collaborations with other organizations or individuals.
- Make decisions about specific technical issues, features, bugs and pull requests. They are the primary mechanism of guiding the code review process and merging pull requests.
- Make decisions about the Services that are run by The Project and manage those Services for the benefit of the Project and Community.
- Make decisions when regular community discussion doesn’t produce consensus on an issue in a reasonable time frame.
### Board Membership
All community and end-user community member positions are appointed for 12-months and are expected to rotate under the consensus and discretion of the BDFLs.
To become eligible for a Community Member board position, an individual should meet some of the following criteria:
- Be a Project Contributor who has produced contributions that are substantial in quality and quantity.
- Sustain this development consistently over several months.
- Support the community through various activities (some examples below):
- code review
- answering user questions
- triaging bug reports
- participating constructively in broader conversations
- contributing to documentation
- maintaining infrastructure
- Demonstrate breadth by supporting the community outside of their particular work interests or sub-project
- Be civil in public discourse
We are currently looking to fill the position for two end-user community members! Please reach out to the Pixie project team to apply.
## Conflict of interest
It is expected that the Governance Board and BDFL will be employed at a wide range of companies, universities and non-profit organizations. Because of this, it is possible that Members will have conflict of interests. Such conflict of interests include, but are not limited to:
- Financial interests, such as investments, employment, or contracting work, outside of The Project that may influence their work on The Project.
- Access to proprietary information of their employer that could potentially leak into their work with the Project.
- An issue where the person privately gains an advantage from The Project resources, but The Project has no gain or suffers a disadvantage.
All members of the Governance Board, BDFL included, shall disclose to the rest of the Board any conflict of interest they may have. If the BDFL has recused themselves for a particular decision, they will appoint the deputy BDFL for that decision. If the deputy BDFL has also recused themselves for that decision, they will appoint a substitute BDFL.
## Voting
In general, the Board makes decisions by lazy consensus with a minimum of participation based on the importance of the decisions to be made. Conversations happen on public GitHub or JIRA issues for most cases, and through private e-mail for more sensitive issues.
To make a decision the Board discusses the topic, a proposal is made, and a suitable wait time occurs for Board members to either agree or veto. By consensus we mean that any Board member can veto a decision with justification. By lazy we mean that not all Board members must participate, and that absence is interpreted as assent. By a minimum of participation we mean that we require the participation of a certain number of individuals based on the importance of the issue; for non-contentious issues a single Board member may move forward after a suitable time, while for contentious issues we will often require a few, often from different institutions.
## Private communications of the Board
Unless specifically required, all Board discussions and activities will be public and done in collaboration and discussion with the Project Contributors and Community. The Board will have a private mailing list that will be used sparingly and only when a specific matter requires privacy. When private communications and decisions are needed, the Board will do its best to summarize those to the Community after eliding personal/private/sensitive information that should not be posted to the public internet.
# Changing the Governance Documents
Changes to the governance documents are submitted via a GitHub/Phabricator pull request to The Project's governance document. The pull request is then refined in response to public comment and review, with the goal being consensus in the community. Since the BDFL holds ultimate authority in The Project, the BDFL has authority to act alone in accepting or rejecting changes.
# Inclusive Style Guide
We write our code, documentation, review comments, and other assets with inclusivity and diversity in mind. This page is not an exhaustive reference but describes some general guidelines and examples that illustrate some best practices to follow. These are only suggestions. The author, reviewers, and project maintainers will make the final call.
## Avoid ableist language
When trying to achieve a friendly and conversational tone, problematic ableist language may slip in. This can come in the form of figures of speech and other turns of phrase. Be sensitive to your word choice, especially when aiming for an informal tone. Choose alternative words depending on the context.
Things to avoid:
- Phrases referring to mental health: sanity / crazy / insane
- Words related to physical or mental disabilities: blind / cripple / dummy
How to fix ableist language:
- Try replacing the word with a phrase that has no underlying negative connotations. Example: “crazy outliers” → “baffling outliers”, “dummy variable” → “placeholder variable”.
## Use gender-neutral language
Some points in our code, documentation and comments contain needless assumptions about the gender of a future reader, user, etc. Example: “When the user logs into his profile.”
Things to avoid:
- Gendered pronouns: he / she / him / her / his / hers, etc.
- Instances of the phrases “he or she”, “his/hers”, “(s)he”, etc. All of these still exclude those who don't identify with either gender, and implicitly (slightly) favor one gender via listing it first.
- “Guys” as a gender-neutral term, which has male associations. Usually in comments it implies anthropomorphism of inanimate objects and should be replaced with a more precise technical term. If it does refer to people, consider using “everyone”, “folks”, “people”, “peeps”, “y'all”, etc.
- Other gendered words: “brother”, “mother”, “man”, etc.
Cases that are likely fine to leave alone include:
- References to a specific person (“Rachel is on leave; update this when she is back.”).
- A name (“Guy” and “He” are both valid names).
- A language code (“he” is the ISO 639-1 language code for Hebrew).
- He as an abbreviation for “helium”.
- The Spanish word “he”.
- References to a specific fictional person (Alice, Bob, ...).
- For new code/comments, consider using just ‘A’, ‘B’ as names.
- Quotations and content of things like public-domain books.
- Partner agreements and legal documents we can no longer edit.
- Occurrences in randomly generated strings or base-64 encodings.
- Content in a language other than English unless you are fluent in that language.
How to fix gendered language:
- Try rewording things to not involve a pronoun at all. In many cases this makes the documentation clearer. Example: “I tell him when I am all done.” → “I tell the owner when I am all done.” This saves the reader a tiny bit of mental pointer-dereferencing.
- Try using singular they.
- Try making hypothetical people plural. “When the user is done he'll probably...” → “When users complete this step, they probably...”.
- When referring to a non-person, “it” or “one” may be good alternatives (wikipedia link).
## Use racially-neutral language
Some phrases have underlying racial connotations, or reinforce the notion that some races are better than others.
Things to avoid:
- Terms that reinforce the notion that one race is good or bad: blacklist, whitelist
- Words rooted in historical events regarding race: slave, master
How to fix racist language:
- Replace the term with an alternative that does not change its meaning. Example: “whitelist” → “allowlist”, “master” → “main”.
# References:
- https://developers.google.com/style/inclusive-documentation
- https://chromium.googlesource.com/chromium/src/+/master/styleguide/inclusive_code.md
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment