From 00c78b0f11db13a76444a023b2a780d2bce4ee6c Mon Sep 17 00:00:00 2001 From: Erich Gubler Date: Wed, 26 Jun 2024 10:06:11 -0600 Subject: [PATCH] fixup!: meta: add `CONTRIBUTING.md` --- CONTRIBUTING.md | 56 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 41 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 568054ff5c8..484be175db2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,35 +3,38 @@ This document is a guide for contributions to the WGPU project. ## Welcome! First of all, welcome to the WGPU community! 👋 We're glad you want to -contribute. If you are unfamiliar with the WGPU community as an organization, we -recommend you read [`GOVERNANCE.md`] for an overview of how it works. +contribute. If you are unfamiliar with the WGPU project, we recommend you read +[`GOVERNANCE.md`] for an overview of its goals, and how it's governed. [`GOVERNANCE.md`]: ./GOVERNANCE.md ## Talking to other humans in the WGPU project -The WGPU project has multiple ways to engage: +The WGPU project has multiple official platforms for community engagement: -- [GitHub discussions]: TODO: not sure when to use this over Matrix and issues. - TBH. - The Matrix channel [`wgpu:matrix.org`](https://matrix.to/#/#wgpu:matrix.org) is dedicated to informal chat about contributions the project. It is particularly useful for: + - …saying hello, and introducing yourself. - …validating contributions (i.e., determining if they'll be accepted, ensuring your approach is correct, making sure you aren't wasting effort, etc.) - …setting expectations for contributions - Notification in Matrix can sometimes be unreliable. Feel free to explicitly tag - people from whom you would like attention (but don't abuse it!), and follow-up - after a day or so if you do not get a response to your messages. + Notification in Matrix can sometimes be unreliable. Feel free to explicitly + tag people from whom you would like attention, esp. to follow-up after a day + or so if you do not get a response to your contributions. -- [GitHub issues] are for action items that the community needs to prioritize. - These could be items of work resolved by pull requests, decisions to make with - a formal outcome, or collections of issues needed for a specific feature or - use case (AKA `[meta]` issues). +- [GitHub issues] are for tasks that the community intends to work on. + We use these in several ways: + - Noting work that needs resolution via pull requests, + - Recording project decisions formally. + - Compiling sets of other issues needed for a specific feature or use case + (AKA `[meta]` issues). - [GitHub pull requests]: TODO +- [GitHub discussions]: TODO: Experimentally used by some enthusiastic members + of our community. Not supported officially. [GitHub discussions]: https://github.com/gfx-rs/wgpu/discussions [GitHub issues]: https://github.com/gfx-rs/wgpu/issues @@ -43,15 +46,38 @@ Community response to contributions are, in general, prioritized based on their relevance to WGPU's mission and decision-making groups' interest (see [`GOVERNANCE.md`]). -### "What can I work on?" +### "What can I work on?" as a new contributor TODO +We discourage new contributors from submitting large changes or opinionated +refactors unless they have been specifically validated by WGPU maintainership. +These are likely to be rejected on basis of needing discussion before a formal +review. + ### What to expect when you file an issue TODO +- Describe the filing process + - Link to new issue page + - Describe how to socialize the issue effectively + - Feel free to ping us if it's a blocker! + - Suggesting tags is helpful. + - Describe how the project will handle the issue + - Our ability to respond to an issue depends entirely on whether it is + _actionable_ (viz., that there is a course of action that is reasonable + for a volunteer to take the time to do). If it's not actionable, we + reserve the right to close it. + - Being responsive to requests for further information is important. + - Understanding what point in the repository's history an issue began is + also important. Maybe link to `git bisect` or something similar? + - In particular, expecting others to fix something hardware- or + driver-specific that current maintainership (1) can't mentor you + into fixing and (2) otherwise isn't being prioritized are likely to + be closed. + ### What to expect when you submit a PR -TODO: It is strongly recommended that you validate your contributions before you make -significant efforts… +TODO: It is strongly recommended that you validate your contributions before you +make significant efforts…