From 28f646fd87e824ba5e89377cd9aedde74e6be96c Mon Sep 17 00:00:00 2001 From: Arun Raghavan Date: Fri, 25 Dec 2020 11:10:30 -0500 Subject: [PATCH] doc: Add some contributor guidelines Document some things that should be helpful to at least new contributors. Since we don't have a way to show this when people are creating MRs, also copy over the next to a merge request template so that creates a dropdown that folks might look at when creating an MR. Part-of: --- .gitlab/merge_request_templates/Guidelines.md | 67 +++++++++++++++++++++++++++ CONTRIBUTING.md | 67 +++++++++++++++++++++++++++ 2 files changed, 134 insertions(+) create mode 100644 .gitlab/merge_request_templates/Guidelines.md create mode 100644 CONTRIBUTING.md diff --git a/.gitlab/merge_request_templates/Guidelines.md b/.gitlab/merge_request_templates/Guidelines.md new file mode 100644 index 0000000..2fb9a62 --- /dev/null +++ b/.gitlab/merge_request_templates/Guidelines.md @@ -0,0 +1,67 @@ +# Contribution Guidelines + +## A note for contributors + +Thank you for your contribution! + +Please make sure you tick the box labelled `Allow commits from members who can +merge to the target branch`. This allows us to make minor edits ourselves, and +then automatically rebase and merge your changes. + +PulseAudio is currently maintained by three volunteer developers in their free +time (probably amounting to less than one full time developer), which is not +really enough, given the project size and scope. For this reason bug reports +and patch submissions are sometimes handled very slowly. + +For non-trivial patches, we meet biweekly on IRC to discuss and prioritise +outstanding MRs. If you haven't heard from us a few days after you create the +MR, please take a look at [the patch status +page](https://www.freedesktop.org/wiki/Software/PulseAudio/PatchStatus/). + +If you don't see your MR in that list either, please don't hesitate to drop a +comment pinging us, and we'll try to at least respond and make sure your +request is tracked on that list. + +## Coding Style + +Please take a look at the [coding style +documentation](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/Developer/CodingStyle/) +on our wiki. + +## Commit messagse + +We follow the standard git commit message format of a summary on the first line +(<=50 characterss for preference, <=72 characters otherwise), followed by a new +line, followed by a detailed commit message. An additional line at the end may +link to an issue being fixed by this MR. + +The first line is usually a short description of "what" your commit does, and +the rest of the message describes the "why", along with any additional +information that readers might need to understand the rationale for the change. +If in doubt, more verbose is better than less. + +If you need to describe the "how" of the commit, that is usually best +documented along with the code itself. + +Commit messages are prefixed with the subsystem being affected. Your best bet +to figure out what is appropriate is to look at previous commit messages. An +example: + +``` +sink: Reduce chat sink priority + +Some gaming sound cards have custom profiles with analog-game and +analog-chat mappings that exist simultaneously. The game sink should +have higher priority than the chat sink, but currently there's no way to +affect the sink priorities from the profile-set configuration (the +mapping priority is not propagated to the sink priority). + +I first thought about adding the mapping priority to the sink priority, +but that could mess up the prioritization system in +pa_device_init_priority(). I ended up checking for the intended roles +property to reduce the chat sink priority. I also reduced the iec958 +priority so that the chat and iec958 sinks don't end up with the same +priority. + +Fixes: https://gitlab.freedesktop.org/pulseaudio/pulseaudio/issues/818 +``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2fb9a62 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contribution Guidelines + +## A note for contributors + +Thank you for your contribution! + +Please make sure you tick the box labelled `Allow commits from members who can +merge to the target branch`. This allows us to make minor edits ourselves, and +then automatically rebase and merge your changes. + +PulseAudio is currently maintained by three volunteer developers in their free +time (probably amounting to less than one full time developer), which is not +really enough, given the project size and scope. For this reason bug reports +and patch submissions are sometimes handled very slowly. + +For non-trivial patches, we meet biweekly on IRC to discuss and prioritise +outstanding MRs. If you haven't heard from us a few days after you create the +MR, please take a look at [the patch status +page](https://www.freedesktop.org/wiki/Software/PulseAudio/PatchStatus/). + +If you don't see your MR in that list either, please don't hesitate to drop a +comment pinging us, and we'll try to at least respond and make sure your +request is tracked on that list. + +## Coding Style + +Please take a look at the [coding style +documentation](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/Developer/CodingStyle/) +on our wiki. + +## Commit messagse + +We follow the standard git commit message format of a summary on the first line +(<=50 characterss for preference, <=72 characters otherwise), followed by a new +line, followed by a detailed commit message. An additional line at the end may +link to an issue being fixed by this MR. + +The first line is usually a short description of "what" your commit does, and +the rest of the message describes the "why", along with any additional +information that readers might need to understand the rationale for the change. +If in doubt, more verbose is better than less. + +If you need to describe the "how" of the commit, that is usually best +documented along with the code itself. + +Commit messages are prefixed with the subsystem being affected. Your best bet +to figure out what is appropriate is to look at previous commit messages. An +example: + +``` +sink: Reduce chat sink priority + +Some gaming sound cards have custom profiles with analog-game and +analog-chat mappings that exist simultaneously. The game sink should +have higher priority than the chat sink, but currently there's no way to +affect the sink priorities from the profile-set configuration (the +mapping priority is not propagated to the sink priority). + +I first thought about adding the mapping priority to the sink priority, +but that could mess up the prioritization system in +pa_device_init_priority(). I ended up checking for the intended roles +property to reduce the chat sink priority. I also reduced the iec958 +priority so that the chat and iec958 sinks don't end up with the same +priority. + +Fixes: https://gitlab.freedesktop.org/pulseaudio/pulseaudio/issues/818 +``` -- 2.7.4