diff --git a/docs/submittingpatches.rst b/docs/submittingpatches.rst index 4ba97fda912..5519442fc57 100644 --- a/docs/submittingpatches.rst +++ b/docs/submittingpatches.rst @@ -1,6 +1,64 @@ Submitting Patches ================== +.. _introduction: + +Introduction +------------ + +Mesa contribution is a collaborative process that works like this: +A contributor proposes a change (usually in the form of a GitLab +merge request), which must undergo a review (usually in the form of +comments from the maintainers on the merge request). + +The maintainers either accept it as-is, reject it outright, +or request changes from the contributor before a contribution +can be accepted. + +Mesa is a project that is made up of many different subprojects, +for example drivers, API frontends, shader compiler infrastructure, +etc. Each of these parts may have different maintainers and/or +different rules and conventions. It is up to the maintainers of +each specific part to decide what is acceptable for them and +to direct the development of that part. + +.. _expectations_on_contributors: + +Expectations on contributors +---------------------------- + +Due to the collaborative nature of development, the expectation is that +the contributor engages with the maintainers and works with +us to shape the changeset into a form that can be accepted in the project. + +If you want to contribute code to Mesa, we highly recommend the following: + +- Familiarize yourself with `Git `__. +- Understand the code you write at least well enough to be able + to explain why your changes are beneficial to the project. +- It's up you what tools you use to write code (development environment, + coding assistant, etc.), but keep in mind that no tool can substitute + actual understanding. + +In case you are not familiar with the code base, it's okay to ask for help +and guidance from more experienced developers. + +The submitter is responsible for the code change, regardless of where +that code change came from, whether they wrote it themselves, used an +"AI" or other tool, or got it from someone else. That responsibility +includes making sure that the code change can be submitted under the +MIT license that Mesa uses. + +The submitter needs to understand what code they are changing, +what the change does, and justify that change in the commit messages. +Using coding assistants or "AI" or other tools does not grant additional +privileges or reduce our expectations. + +If you don't know programming (and don't want to learn), but you are +interested in the Mesa project, there are plenty of other ways to +contribute besides writing code, for example reporting bugs, benchmarking, +testing changes, etc. + .. _guidelines: Basic guidelines @@ -188,9 +246,26 @@ Submitting Patches ------------------ Patches are submitted to the Mesa project via a -`GitLab `__ Merge Request. +`GitLab `__ Merge Request (MR). -Add labels to your MR to help reviewers find it. For example: +- Please do NOT submit your patches in email to a mailing list, + we only review patches on GitLab. +- Please do NOT paste your patches as comments in a conversation, + unless it is small or unless that is what the maintainers requested. +- If you are not familiar with how to use git, please learn that + before making a contribution to Mesa. + +When opening a merge request, we recommend the following best practices: + +Add a prefix to the title of the MR to indicate which part of the +codebase is affected. This is helpful to people who receive many MRs +and filter them by title. All commits must also have a prefix. +If you are unsure what is the correct prefix, please check the git +history for the files you are changing and choose based on that. + +If you are already in the 'developer' role, +add labels to your MR to help reviewers find your MR. +For example: - Mesa changes affecting all drivers: mesa - Hardware vendor specific code: AMD common, intel, ... @@ -198,6 +273,8 @@ Add labels to your MR to help reviewers find it. For example: vc4, ... - Other tag examples: gallium, util +If you don't add any labels, a bot will attempt to add the correct ones. + Tick the following when creating the MR. It allows developers to rebase your work on top of main.