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
|
2024-01-08 04:33:04 +00:00
|
|
|
issues](https://github.com/lutris/lutris/issues?q=is%3Aissue+is%3Aopen+label%3A%22can%27t+reproduce%22+)
|
|
|
|
that can't be reproduced on the developers setup. Please make sure that you're able to
|
|
|
|
reproduce an issue before attempting to fix it.
|
2019-03-22 02:27:27 +00:00
|
|
|
|
|
|
|
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
|
2021-03-22 22:26:48 +00:00
|
|
|
agreeing on a design first with the development team. Please get in touch with
|
|
|
|
the developers before writing any code, so that you don't waste your efforts on
|
|
|
|
something that isn't going to be merged. 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
|
2024-01-08 04:33:04 +00:00
|
|
|
the right thing by default. Only introduce new options when absolutely
|
2019-03-22 02:27:27 +00:00
|
|
|
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
|
2020-04-27 18:36:41 +00:00
|
|
|
architectural changes for the sake of "modularity", "Unix pureness" or subjective
|
2024-01-08 04:33:04 +00:00
|
|
|
aspects might not be received warmly. There are no current plans for any rewrite in
|
|
|
|
another language. Once again, make sure to discuss any change with a core developer
|
|
|
|
before writing a large amount of code. Keeping your pull requests as small as a possible
|
|
|
|
is the best way to have them reviewed and merged quickly.
|
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
|
|
|
|
2024-01-08 04:33:04 +00:00
|
|
|
The PyGOject introspection libraries are not regular python packages, for that
|
|
|
|
reason, using a virtualenv for development is heavily discouraged. Make
|
2019-03-22 02:27:27 +00:00
|
|
|
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
|
|
|
|
2020-04-27 18:36:41 +00:00
|
|
|
Set up your development environment
|
|
|
|
-----------------------------------
|
|
|
|
|
2024-01-08 04:33:04 +00:00
|
|
|
To ensure you have the proper tools installed run `make dev`
|
|
|
|
This will install all necessary python to allow testing and validating your code.
|
2020-04-27 18:36:41 +00:00
|
|
|
|
|
|
|
This project includes .editorconfig so you're good to go if you're using any
|
|
|
|
editor/IDE that supports this. Otherwise make sure to configure your max line
|
|
|
|
length to 120, indent style to space and always end files with an empty new line.
|
|
|
|
|
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
|
2020-04-27 18:36:41 +00:00
|
|
|
passes style checks by running `make sc` and fixing any reported issues
|
2024-01-08 04:33:04 +00:00
|
|
|
before submitting your code. This runs a series of tools to apply PEP 8 coding
|
2020-04-27 18:36:41 +00:00
|
|
|
style conventions, sorting and grouping imports and checking for formatting issues
|
|
|
|
and other code smells.
|
2018-10-15 00:14:29 +00:00
|
|
|
|
2020-04-27 18:36:41 +00:00
|
|
|
You can help fix formatting issues or other code smells by having a look at
|
2018-10-19 04:16:34 +00:00
|
|
|
the CodeFactor page: https://www.codefactor.io/repository/github/lutris/lutris
|
|
|
|
|
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
|
2024-01-08 04:33:04 +00:00
|
|
|
the code. Also run the test suite and check that nothing broke.
|
2018-12-22 07:38:35 +00:00
|
|
|
You can run the test suite by typing `make test` in the source directory.
|
|
|
|
|
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
|
2024-01-08 04:33:04 +00:00
|
|
|
you didn't add unit tests. Even trivial changes should be tested
|
2019-03-22 02:27:27 +00:00
|
|
|
as they could potentially introduce breaking changes from a simple oversight.
|
|
|
|
|
2018-10-15 00:14:29 +00:00
|
|
|
Submitting your changes
|
|
|
|
-----------------------
|
|
|
|
|
2024-01-08 04:33:04 +00:00
|
|
|
Make a new git branch based of `master` in most cases. Send a pull request
|
|
|
|
through GitHub describing what issue the patch solves.
|
|
|
|
If the PR is related to and existing bug report, you can add `(Closes #nnnn)`
|
|
|
|
or `(Fixes #nnnn)` to your PR title or message, where `nnnn` is the ticket
|
|
|
|
number you're fixing.
|
|
|
|
|
|
|
|
If you contribute to Lutris on a somewhat regular basis, be sure to add
|
|
|
|
yourself to the AUTHORS file!
|
|
|
|
|
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)
|
|
|
|
|
|
|
|
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
|