From 01e9c407fbf882d4ed7ba31cb93bba4ebded10af Mon Sep 17 00:00:00 2001 From: Mathieu Comandon Date: Thu, 21 Mar 2019 19:27:27 -0700 Subject: [PATCH] Update CONTRIBUTING document --- CONTRIBUTING.md | 71 ++++++++++++++++++++++++++++++++----------------- 1 file changed, 47 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5297683d3..52d9de8ab 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,34 +1,48 @@ Contributing to Lutris ====================== -Finding issues to work on -------------------------- +Finding features to work on +--------------------------- If you are looking for issues to work on, have a look at the [milestones](https://github.com/lutris/lutris/milestones) and see which one is the closest to release then look at the tickets targeted at this release. -If you are less experienced with code, you can also have a look at the issues -that are [not part of a release](https://github.com/lutris/lutris/milestone/29) -which usually include problems with specific games or runners. - Don't forget that lutris is not only a desktop client, there are also a lot of issues to work on [on the website](https://github.com/lutris/website/issues) and also in the [build scripts repository](https://github.com/lutris/buildbot) where you can submit bash scripts for various open source games and engines we do not already have. -Other areas can benefit non technical help. The Lutris UI is far from being -perfect and could use the input of people experienced with UX and design. -Also, while not fully ready, we do appreciate receiving translations for other -languages. Support for i18n will come in a future update. - Another area where users can help is [confirming some issues](https://github.com/lutris/lutris/issues?q=is%3Aissue+is%3Aopen+label%3A%22need+help%22) that can't be reproduced on the developers setup. Other issues, tagged [need help](https://github.com/lutris/lutris/issues?q=is%3Aissue+is%3Aopen+label%3A%22need+help%22) might be a bit more technical to resolve but you can always have a look and see -if they fit your area of expertise. +if they fit your area of expertise. Also, while not fully ready, we do +appreciate receiving translations for other languages, support for i18n will +come in a future update. + +Note that Lutris is not a playground or a toy project. One cannot submit new +features that aren't on the roadmap and submit a pull request for them without +agreeing on a design first with the development team. You can submit such pull +requests but they will have to be updated with necessary changes from code +reviews of the development team. This is not only about writing good code but +also about providing good design for the overall product. Make sure to post all +the revelant information in a ticket or on the pull request. New features must +at all times have a valid use case based on an actual game, be very specific +about why you are implementing a feature otherwise it will get rejected. +Avoid adding options in the GUI or introducing new installer directives for +things that can be automated. Lutris focuses heavily on automation and on doing +the right thing by default. Only introduce new option when absolutely +necessary. + +Contributors are welcome to suggest architectural changes or better code design +if they feel like the current implementation should be improved but please take +note that we're trying to stay as lean as possible. Requests introducing complex +architectural changes for the sake of "modularity", "Unix pureness" or subjective +aspects might not be received warmly. There are no plans for any rewrite in +another language or switching to another toolkit. Running Lutris from Git ----------------------- @@ -41,33 +55,35 @@ the repository and executing Lutris from there. ./bin/lutris -d Make sure you have all necessary dependencies installed. It is recommended that -you keep a stable copy of the client installed with your package manager to +you keep a copy of the stable version installed with your package manager to ensure that all dependencies are available. -If you are working on a branch implementing new features, such as the `next` -branch, it might introduce new dependencies. Check in the package configuration -files for new dependencies, for example Debian based distros will have their -dependencies listed in `debian/control` and in `lutris.spec` for RPM based -ones. +If you are working on newly written code that might introduce +new dependencies, check in the package configuration files for new packages to +install. Debian based distros will have their dependencies listed +in `debian/control` and RPM based ones in `lutris.spec`. Under NO circumstances should you use a virtualenv or install dependencies with pip. The PyGOject introspection libraries are not regular python packages and -it is not possible to pip install them or use them from a virtualenv. Make -sure to always use PyGOject from your distribution's package manager. +it is not possible for pip to install them or use them from a virtualenv. Make +sure to always use PyGOject from your distribution's package manager. Also +install the necessary GObject bindings as described in the INSTALL file. Formatting your code -------------------- To ensure getting your contributions getting merged faster and to avoid other -developers from going back and fixing your code, please make your code pass the -pylint checks. We highly recommend that you install a pylint plugin for your -code editor. Once you have pylint set up to check the code, you can configure -it to use 120 characters max per line instead of 80. +developers from going back and fixing your code, please make sure your code +passes pylint checks. We highly recommend that you install a pylint plugin in +your code editor. Once you have pylint set up to check the code, you can +configure it to use 120 characters max per line instead of 80. You can help fixing formatting issues or other code smells by having a look at the CodeFactor page: https://www.codefactor.io/repository/github/lutris/lutris When writing docstrings, you should follow the Google style (See: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) +You should always provide docstrings, otherwise your code wouldn't pass a +Pylint check. Do *not* add type annotations, those are not supported in Python 3.4. @@ -88,6 +104,13 @@ In order to run the test, you'll need to install nosetests and flake8: pip3 install nose flake8 +QAing your changes +------------------ + +It is very important that any of your changes be tested manually, especially if +you didn't add unit tests for the patch. Even trivial changes should be tested +as they could potentially introduce breaking changes from a simple oversight. + Submitting your changes -----------------------