From 780b0365c98d05fbbf33a5d33a2445d546efa6a9 Mon Sep 17 00:00:00 2001 From: Robert Ancell Date: Fri, 11 Nov 2022 00:10:00 +0100 Subject: [PATCH] Rewrite the contribution guidelines. In particular set the expectation for reviews and document when MRs will be closed due to inactivity. --- docs/CONTRIBUTING.md | 112 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 91 insertions(+), 21 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index c6faebf12..c592429d9 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,27 +1,97 @@ # Contributing -When contributing to the development of GNOME Settings, please first discuss the change you wish to -make via issue, email, or any other method with the maintainers before making a change. +Thank you for considering contributing to Settings! + +All code contributions are made using merge requests. Please note we have a Code of Conduct, please follow it in all your interactions with the project. -## Pull Request Process +## Creating Merge Requests -1. Create a fork in GitLab and push your work to there -2. Open a Merge Request - 1. Always allow maintainer edits - 2. Mark the Merge Request as WIP if your work is not ready to be reviewed -3. Assign the correct maintainer to the Merge Request (see [`MAINTAINERS.md`][maintainers] to select - the correct maintainer) -4. Format commit messages as follows: - ``` - component: - ‌ - A paragraph explaining the problem and its context. - ‌ - Another one explaining how you solved that. - ‌ - - ``` -4. You may merge the pull request in once you have the sign-off of the maintainers, or if you - do not have permission to do that, you may request the second reviewer to merge it for you. +To open a merge request fork the Settings project, and then create a branch for your change. +When the change is ready, submit a merge request. + +The following guidelines will help your change be successfully merged: + + * Keep the change as small as possible. If you can split it into multiple merge requests please do + so. + * Use multiple commits. This makes is easier to review and helps to diagnose bugs in the future. + * Use clear commit messages (see below). + * Attach screenshots of the change. + * Link to relevant issues this change is related to. + * Always set the merge request to allow maintainer edits - this makes it easier + for a maintainer to make small improvements to land the change faster. + +Please format commit messages as follows: + +``` +component: + +A paragraph explaining the problem and its context. + +Another one explaining how you solved that. + + +``` + +## Bug Fixes + +Changes that fix bugs include: + + * Correcting code that crashes. + * Spelling mistakes in labels. + * Small layout issues (e.g. spacing). + * Use of deprecated APIs. + * Restructuring of code for improved safety. + +Please include clear information in the commit message(s) and merge request that indicate what is +being fixed by the change. + +These changes will be reviewed for correctness, and then merged once this is complete. + +## User Experience Changes + +Changes that impact the user experience of Settings require approval from the +[Design Team][design-team]. This includes: + + * Addition or removal of features in existing panels. + * Changes to the layout of panels. + * New panels. + +Please include before/after screenshots in the merge request to show what is being changed. + +For one of these changes to be merged one of the following is required: + + * The change is shown in an existing mockup done by the design team (linked to in the merge request + or issue). + * A comment from a design team member in the merge request or issue approving the change. + +If a merge request is opened without the above the "Needs Design" label attached to it and will not +be merged until design approval is received. + +Once design approval is obtained, the change will be reviewed for correctness, and then merged once +this is complete. +If design approval is not obtained, the merge request will be closed. + +[design-team]: https://gitlab.gnome.org/Teams/Design + +## Reviews + +All changes require approval from one or more Settings maintainers. +Reviews are likely to ask for changes to be made, please respond to these as soon as you are able +and ask for clarification if the requests are not clear. + +When the change is ready to land a maintainer will mark it as approved. +Then the change can be merged by either a maintainer or the submitter if they have suitable +permissions. + +## Draft Merge Requests + +Merge requests marked as draft will not be reviewed by Settings maintainers or merged. +When the change is ready for review please mark the merge request as ready. + +## Inactive Merge Requests + +If a merge request has comments from maintainers that have not been responded to within 4 weeks this +merge request is considered to be inactive and will be closed. The reporter may re-open it at a +later date if they respond to the comments.