2018-10-20 20:20:31 +00:00
|
|
|
Contributing to Lutris
|
|
|
|
======================
|
2018-10-15 00:14:29 +00:00
|
|
|
|
2019-03-22 02:27:27 +00:00
|
|
|
Finding features to work on
|
|
|
|
---------------------------
|
2018-10-15 00:14:29 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2019-09-08 11:16:08 +00:00
|
|
|
Don't forget that Lutris is not only a desktop client, there are also a lot of
|
2018-10-15 00:36:24 +00:00
|
|
|
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.
|
|
|
|
|
2018-10-15 01:25:23 +00:00
|
|
|
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
|
2019-03-22 02:27:27 +00:00
|
|
|
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
|
2019-09-08 11:16:08 +00:00
|
|
|
the relevant information in a ticket or on the pull request. New features must
|
2019-03-22 02:27:27 +00:00
|
|
|
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.
|
2018-10-15 01:25:23 +00:00
|
|
|
|
2018-10-19 02:12:21 +00:00
|
|
|
Running Lutris from Git
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
Running Lutris from a local git repository is easy, it only requires cloning
|
|
|
|
the repository and executing Lutris from there.
|
|
|
|
|
|
|
|
git clone https://github.com/lutris/lutris
|
|
|
|
cd lutris
|
|
|
|
./bin/lutris -d
|
|
|
|
|
|
|
|
Make sure you have all necessary dependencies installed. It is recommended that
|
2019-03-22 02:27:27 +00:00
|
|
|
you keep a copy of the stable version installed with your package manager to
|
2018-10-19 02:12:21 +00:00
|
|
|
ensure that all dependencies are available.
|
2019-03-22 02:27:27 +00:00
|
|
|
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`.
|
2018-10-19 02:12:21 +00:00
|
|
|
|
2018-10-20 20:30:13 +00:00
|
|
|
Under NO circumstances should you use a virtualenv or install dependencies with
|
|
|
|
pip. The PyGOject introspection libraries are not regular python packages and
|
2019-03-22 02:27:27 +00:00
|
|
|
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.
|
2018-10-20 20:30:13 +00:00
|
|
|
|
2018-10-15 00:14:29 +00:00
|
|
|
Formatting your code
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
To ensure getting your contributions getting merged faster and to avoid other
|
2019-03-22 02:27:27 +00:00
|
|
|
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.
|
2018-10-15 00:14:29 +00:00
|
|
|
|
2018-10-19 04:16:34 +00:00
|
|
|
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
|
|
|
|
|
2018-12-04 00:28:40 +00:00
|
|
|
When writing docstrings, you should follow the Google style
|
|
|
|
(See: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
|
2019-03-22 02:27:27 +00:00
|
|
|
You should always provide docstrings, otherwise your code wouldn't pass a
|
|
|
|
Pylint check.
|
2018-12-04 00:28:40 +00:00
|
|
|
|
2018-12-22 07:39:49 +00:00
|
|
|
Do *not* add type annotations, those are not supported in Python 3.4.
|
2018-12-04 00:28:40 +00:00
|
|
|
|
2018-10-15 00:14:29 +00:00
|
|
|
Writing tests
|
|
|
|
-------------
|
|
|
|
|
|
|
|
If your patch does not require interactions with a GUI or external processes,
|
|
|
|
please consider adding unit tests for your code. Have a look at the existing
|
|
|
|
test suite in the `tests` folder to see what kind of features are tested.
|
|
|
|
|
2018-12-22 07:38:35 +00:00
|
|
|
Running tests
|
|
|
|
-------------
|
|
|
|
|
|
|
|
Be sure to test your changes thoroughly, never submit changes without running
|
|
|
|
the code. At the very least, run the test suite and check that nothing broke.
|
|
|
|
You can run the test suite by typing `make test` in the source directory.
|
|
|
|
In order to run the test, you'll need to install nosetests and flake8:
|
|
|
|
|
|
|
|
pip3 install nose flake8
|
|
|
|
|
2019-03-22 02:27:27 +00:00
|
|
|
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.
|
|
|
|
|
2018-10-15 00:14:29 +00:00
|
|
|
Submitting your changes
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
Make a new git branch based of `master` in most cases, or `next` if you want to
|
2019-09-08 11:16:08 +00:00
|
|
|
target a future release. Send a pull request through GitHub describing what
|
2018-10-15 00:14:29 +00:00
|
|
|
issue the patch solves. If the PR is related to and existing bug report, you
|
|
|
|
can add `(Closes #nnn)` or `(Fixes #nnn)` to your PR title or message, where
|
|
|
|
`nnn` is the ticket number you're fixing. If you have been fixing your PR with
|
|
|
|
several commits, please consider squashing those commits into one with `git
|
|
|
|
rebase -i`.
|
2018-10-15 00:56:48 +00:00
|
|
|
|
|
|
|
Developer resources
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
Lutris uses Python 3 and GObject / Gtk+ 3 as its core stack, here are some
|
|
|
|
links to some resources that can help you familiarize yourself with the
|
|
|
|
project's code base.
|
|
|
|
|
|
|
|
* [Python 3 documentation](https://docs.python.org/3/)
|
|
|
|
* [PyGObject documentation](https://pygobject.readthedocs.io/en/latest/)
|
|
|
|
* [Python Gtk 3 tutorial](https://python-gtk-3-tutorial.readthedocs.io/en/latest/objects.html)
|
|
|
|
* [Fakegir GObject code completion](https://github.com/strycore/fakegir)
|
|
|
|
|
|
|
|
Project structure
|
|
|
|
-----------------
|
|
|
|
|
2018-10-15 00:57:56 +00:00
|
|
|
[root]-+ Config files and READMEs
|
|
|
|
|
|
|
|
|
+-[bin] Main lutris executable script
|
|
|
|
+-[debian] Debian / Ubuntu packaging configuration
|
|
|
|
+-[docs] User documentation
|
|
|
|
+-[lutris]-+ Source folder
|
|
|
|
| |
|
|
|
|
| +-[gui] Gtk UI code
|
|
|
|
| +-[installer] Install script interpreter
|
|
|
|
| +-[migrations] Migration scripts for user side changes
|
|
|
|
| +-[runners] Runner code, detailing launch options and settings
|
|
|
|
| +-[services] External services (Steam, GOG, ...)
|
|
|
|
| +-[util] Generic utilities
|
|
|
|
|
|
|
|
|
+-[po] Translation files
|
|
|
|
+-[share] Lutris resources like icons, ui files, scripts
|
|
|
|
+-[tests] Unit tests
|