-
Notifications
You must be signed in to change notification settings - Fork 50
Contributing
There are many ways to contribute to Cairo-Dock, depending on your skills, interests and free time :)
- Using and testing
- Editing the Wiki
- Writing translations
- Creating themes
- Writing external plug-ins
- Writing plug-ins in C
- Contributing to core
You can already help a lot by just using Cairo-Dock and reporting any issues you experience. Cairo-Dock has tons of features and supports a wide range of desktop environments; however, this means that we cannot always test all configurations, and easily there can be bugs that happen under specific conditions. Please open a new issue if you experience any problems, or if you feel a particular feature is missing. You can also use the Discussions page for more general questions and suggestions.
If you are able to compile Cairo-Dock from source, it is very helpful if you regularly update it based on the latest master branch and thus can help spotting any regressions early. Alternatively, if you're on Ubuntu, you can use our unstable PPA that gets regularly updated based on the latest development version.
Beyond everyday usage, if you are willing to invest some extra effort, it is really helpful if you're able to try out Cairo-Dock under an alternative DE / WM and report any problems you experience. Also, testing alternate settings / themes is very helpful. If you'd like to experiment with Cairo-Dock without messing up your regular settings, you can set an alternative configuration directory by running it from a terminal and either:
- using the
-dcommand line option, e.g.cairo-dock -d ~/config-test - setting the
XDG_CONFIG_HOMEenvironment variable, e.g.env XDG_CONFIG_HOME=$HOME/config-test cairo-dock
- Please first read the Troubleshooting section to see whether it is an already known issue.
- Also please check the existing issues
- Please try to include as much information as possible, even if it seems obvious. Especially important are the desktop environment / window manager / Wayland compositor you're running, the version of Cairo-Dock, the theme / settings you use and the graphics card you have. If possible, copy the contents of the "Technical info" page from the About dialog (right click on the dock -> Cairo-Dock -> About) or the summary information that gets printed out when you start Cairo-Dock
- By default, Cairo-Dock will try to restart itself if it crashes. So a bug that results in a crash might manifest itself as just some strange behavior (the dock "blinks" for a moment, dialogs / menus disappear, settings or themes not applied). You can disable this by running Cairo-Dock from a terminal as
cairo-dock -T, and confirm that what you see is indeed a crash - It is very helpful if you're able to compile the latest version (the master branch on Github) and also any fix we might propose. However, even if you're not able to, reporting an issue is very useful -- we will hopefully be able to reproduce and fix it.
- If the issue is a crash, it is helpful if you are able to run (possibly a debug build) in gdb and provide a stacktrace. You can find more information on how to do this on our old wiki (I'm planning to move this info to the new wiki as well)
- If the issue could be a security vulnerability, you can report it confidentially via encrypted email. See the security policy for more info.
Anyone should be able to edit content in this Wiki (but let us know if you have problems). You can help out by adding any important content that you feel is currently missing.
- Had some issues installing or compiling Cairo-Dock? Feel free to update the information on these pages to be more accurate. It is especially
- Are you maintaining a Cairo-Dock package? Feel free to add a link on the Installation page! Also, please consider editing the Packaging page with any useful information that you found out.
- Were you able to run Cairo-Dock on a new Wayland compositor? Please consider adding the relevant information and a link to the Wayland support page
- Did you encounter an issue that likely affects other users? Please consider adding some information and any workarounds to the Troubleshooting
- Do you have useful information to share with other Cairo-Dock users? Feel free to add it to the Tips & tricks page (which is currently empty)
Cairo-Dock already supports many languages, but coverage varies a lot -- you might see half of the UI in your native language and half in English. You can help by submitting new translations on our Launchpad page. Typically, translations will be updated before each new stable release.
Cairo-Dock comes with many user-contributed themes, currently available in a separate repository. You can help by testing existing themes, updating them (if you experience any issues), or suggesting new themes if you found a particularly nice way to use Cairo-Dock. To suggest a new or updated theme, please use our Discussions page or issue tracker.
Please note that we can only accept contributions under a suitable open source license (GPL, CC, etc.).
Even if you don't like coding in C, you can write plug-ins, using the powerful DBus interface that allows plug-ins to be written in several languages, including Python. While a bit more limited than the C API, many features can be achieved by just a couple of lines of code e.g. in Python.
A collection of external plug-ins is available in a separate repository. These can be installed by simply downloading them and copying the folder of the specific plug-in under ~/.config/cairo-dock/third-party). Note the plug-ins in this repository have not been updated for a long time and some may not work anymore. It is very helpful if you are able to test them, report any issues, and possibly suggest fixes.
If none of the current plug-ins suits your needs, feel free to suggest plug-ins with new functionality! If it is potentially interesting for users, we'd be happy to include it in our repository (as long as you release it under a compatible open-source license, e.g. GPL, MIT, etc.).
Note: plug-ins in the extra repository are currently not easily discoverable as users need to separately download them. In a future release, we are planning to make it easier for users to install such plug-ins and also potentially package them. However, we would need more testing for this, so any feedback you are able to provide on the current plug-ins is very helpful!
Cairo-Dock comes with a wide selection of plug-ins that provide both essential and optional functionality. These are written in C using an API provided by Cairo-Dock, including a set of macros that cover common functionality. See here for some general information to get started.
You can help out by:
- testing and reporting issues with existing plug-ins (some are maintained more regularly than others)
- stepping up to maintain a plug-in that you care about
- suggest new plug-ins to be included
Feel free to use our Discussions page or issue tracker to ask question about contributing to a plug-in.
To keep things simple, we would ask to license your contributions included in our reporitory under GPLv3 (see below as well).
We aim to provide the tools for Cairo-Dock to integrate well into various desktop environments. Currently we provide "*-integration" plug-ins for GNOME, KDE and xfce -- what these do is provide DE-specific functions for opening settings, locking the screen, emptying the trash, logging out, etc. If you use another DE that could benefit from more specific integration, it would help a lot if you're able to provide this as a plug-in -- you can just start by copying code from one of the existing plug-ins and filling in the functions that matter. You'd probably also need a good way to detect your DE that might need some modifications in core as well. Just open an issue to let us know what you need or a PR and we'd be happy to add it as needed.
If you have some knowledge of C, you can likely contribute to some of the core features of Cairo-Dock as well! How to get started:
- Make sure you can compile and install the latest version, including any changes you make.
- Have a look at our API reference, available here, or you can generate it yourself by running
doc/generate-doc.sh - Feel free to ask any questions on our Discussions page
What to work on:
- If you notice any small issue and have a fix, feel free to just open a pull request. Please make sure to describe the issue in enough detail
- Have a look at the planned features. If there's anything there you're interested in, please just comment there to announce your intent to work on it (so that we don't work on the same thing in parallel).
- If you notice any other bug or there is some other feature you'd like to work on, please open a new issue to describe it and state your intent to work on it.
- Many of the code to integrate with a specific DE / WM / compositor is under src/implementations (beyond the "*-integration" plug-ins that also deal with some DE-specific features) and implements one of several well-defined "backends". If you'd like Cairo-Dock to better support a specific environment, you could consider implementing the necessary functions here; you can take inspiration of the existing implementations. E.g. you can look at the current implementation of window management protocols, or integration features with specific window managers.
Some practicalities:
- Cairo-Dock is distributed under GPLv3. We do not have any plans to change this (this would also be impractical given the large number of past contributors). Any of your contributions would also need to be put under the same license. Specifically, you need to either:
- Assign copyright on your contribution to the "Cairo-Dock project", to be distributed under GPLv3 by us.
- Keep copyright and license your contribution to us under the GPLv3. You can do this by adding yourself to the copyright file under the appropriate section (typically this would mean creating a new section that lists the files you have edited, adds a copyright notice with your name and specifies the license as GPL-3+; please see here for the format used).
- By opening a PR, you attest that you are the author of any code involved and you agree to the above regarding copyright. Of course, this only concerns code that becomes part of Cairo-Dock; you still retain rights to code you write and can use it in other projects under whatever license you prefer. You also attest that no one else can claim copyright on your contribution (e.g. your employer, or any AI service you might have used).
- Please be prepared that we might request some changes before your PR is merged. This is to ensure that your contribution fits within the general structure of the code and follows our coding style. Please do not take any such requests as personal criticism; we are very happy that you'd like to contribute!
- Feel free to open a draft PR if you have not yet worked out every detail. As time allows, we are happy to test it and give feedback.