Contributing

Introduction

Thank you for considering making a contribution to conky. Conky is as good as it is thanks to over a decade of steady contributions from people like yourself.

These guidelines are designed to make things easy for both you and the current project maintainers. They will guide you through everything you should know about our workflow in order to streamline the process of making your first and subsequent contributions.

Conky welcomes most contributions that would benefit the wider community. Things like adding new measurements, improving existing features or fixing bugs are something you can create a pull request for without asking.

If you would like to discuss your ideas before committing to writing a PR, you can do so on the idea discussions page. This can save you a lot of time in case an idea isn't something that can be accepted into conky (though there's very few of those).

Improving documentation, bug triaging, or improving this wiki are all examples of helpful contributions.

Please, don't use the issue tracker for support questions. Conky has a Q&A discussions page for those. This helps us maintain our momentum while tackling bugs/issues.

Ground Rules

In order to make contributing to conky the best possible experience for everyone, we've outlined these ground rules.

Responsibilities

Members of the conky community are expected to be open, considerate, and respectful. We have outlined some examples of behaviors we see as good for the project and keeping the positive environment:

Being open to collaboration, whether it's on issues, discussion of ideas, PRs, or otherwise.
- Focusing on what is best for the project and the processes set forth by the community, and working within them.
- Acknowledging time and effort of others, keeping in mind that most labor was completed simply for the good of the community.
Being respectful of differing viewpoints and experiences, experiences and skill sets of all community members contribute to the whole of the project.
- Gracefully accepting constructive comments and criticism.
- When disagreeing, being courteous in raising issues.
- Being respectful of others - their positions, their skills, their efforts and their identities.
Showing empathy towards other community members, being attentive in communication, and tactful when approaching differing views.
- Using welcoming and inclusive language, accepting of all who wish to take part in development of conky
- Fostering an environment where anyone can participate and everyone can make a difference.

We're all here to make conky better, the best way of achieving that is though civil and open-ended communication.

Inappropriate behavior

In order to avoid awkward situations, we'd also like to outline some examples of behavior which is deemed inappropriate and won't be tolerated:

Harassment of any participants in any form
Deliberate intimidation, stalking, or following
Logging or taking screenshots of online activity for harassment purposes
Publishing others' private information, such as a physical or electronic address, without explicit permission
Violent threats or language directed against another person
Incitement of violence or harassment towards any individual
Creating additional online accounts in order to harass another person or circumvent a ban
Sexual language and imagery
Insults, put downs, or jokes that are based upon stereotypes, that are exclusionary, or that ridicule others
Excessive swearing
Unwelcome sexual attention or advances, including simulated physical contact (e.g. textual descriptions like "hug" or "backrub") without consent or (especially so) after a request to stop
Pattern of inappropriate social contact, such as requesting/assuming inappropriate levels of intimacy with others
Sustained disruption of online community discussions and spam

If you are told to stop with any inappropriate behavior, you are expected to stop immediately. If you don't comply, you will be removed from the project.

Licensing

Unless you explicitly state otherwise, your contributions will be licensed under the GPLv3 license. A very brief summary of GPLv3 license is:

Anyone can copy, modify and distribute conky.
The license and copyright notice has to be included with each and every distribution of conky.
Anyone can use conky software privately.
Anyone can use conky for commercial purposes, but if they build their entire business solely on conky, they risk open-sourcing their whole code base.
If someone modifies conky and distributes it separately, they have to indicate changes made to the code.
Any modifications of conky MUST be distributed with the same license, GPLv3.
Conky is provided without warranty, i.e. no one can sue conky maintainers or you for any damages that arise from using it.

Some parts of the project use different licenses (BSD), but due to the nature of the GPLv3 license, it's safest to treat the project as a whole as if it's licensed solely under GPLv3. If you're contributing to conky on company time and/or hope to use parts of its code for commercial purposes, please consult your legal team or supervisor about doing so safely.

In case you're making personal contributions, you don't need to worry about the license too much, just know that other people can use your code outside of conky. Parts of your code might even end up in some commercial code (though that's rare). Most importantly though, the no warranties part of the license means you can't be blamed or sued for making a "bad contribution" so don't worry about that - if conky contributors believe your PR is in the best interest of the project, they will accept your changes.

Your First Contribution

If you're not sure where to start with contributing to conky, there might be some issues marked with gfi label, these should be straightforward to fix and as such are best suited for people who aren't yet familiar with the project or not as savvy with C++. Alternatively, you can also take a look at currently open bugs to see whether you could help with any of those.

Some issues are marked with the help wanted label, with these we could use some help. These are not best suited for those new to the project due to their complexity or scope, but we'd especially value those contributions.

If you're new to git and have never made a contribution to another project, GitHub has a lot of good resources that outline how you would go about doing that:

The official git website contains a lot of documentation and a free book on how to use git. We recommend these as they're official, really well written (and maintained), and completely free.

Code Structure

Avoid Adding to Global State

State (and side effects) are unavoidable in software development and they can greatly simplify logic in some cases. On the flip side, it also introduces invisible and hard-to-reason-about entanglement between different parts of code.

It makes sense to add global state if that state is only going to be accessed from a single place (i.e. class/function) across multiple instantiations or calls (e.g. cache, registry), but if you'll have to access that same information from multiple places in code, please consider wrapping the data in a struct/class, or adding it to an already existing one, and passing it through via function arguments.

Depending on state from other headers makes the code very sensitive to order of #includes, and makes the compilation very slow and memory expensive, as well as complicating subsequent changes.

If at all possible, instead of adding separate globals, try incorporating them into already existing global structs (e.g. window).

Submitting a PR

Document changes

If your PR adds or changes configuration options, Lua API, or conky.text variables, make sure to apply appropriate modifications to the existing documentation. The documentation for those is tracked through YAML config files:

configuration options (doc/config_settings.yaml)
Lua API (doc/lua.yaml)
conky.text variables (doc/variables.yaml)

These are important resource for conky users and helps them discover functionality without digging through piles of code.

If your contribution requires a more in-depth explanation, you should add a guide to this wiki.

Labels

Labels are an important tool for tracking changes in the source code. If you're adding new files which fall into one of known categories, please add those files to labeler.yml file.

Besides just making PRs easy to navigate, that file serves the purpose of helping future contributors navigate the sources they're not yet familiar with based on issue labels.

Prevent Regression

If your contribution can be tested (e.g. parsing color names), by adding a test to conky you ensure other contributors' changes won't break your code in the future. Conky uses Catch2 for testing, check out their README for a quick example and links to more resources.

Some features, like those affecting the UI, can't be (easily) tested though, and in those cases it's fine to skip writing tests. Just make sure to test the changes locally before requesting a review.

Reduce PR Footprint

In order to make it easier to track down bugs, keep the PRs as simple as possible. They should ideally address only a single item/issue and not contain any changes to the rest of the code base, especially those which might affect behavior of unrelated code. It might be a bit cumbersome to create multiple PRs when you've already checked out the code and see something else that you can fix or improve, but keeping commits to main granular helps everyone by making it easier to track down bugs.

Please, keep the following in mind:

It takes up a lot of reviewer's time if they have to go though a lot of unrelated code.
Keeping track of a lot of moving parts it difficult and prone to errors, both while writing code and to review.
It's also really difficult to figure out what exactly is causing the issue in merged code if the problematic commit touched 10+ files.

When you're done with making changes, take a look at the resulting diff and see if there's any obvious ways you could reduce its size. Examples of doing this are removing unnecessary includes, functions you wrote but didn't end up using, extra empty lines or variable name changes, etc.

Request a Review

Conky repository settings require at least one approval in order for you to merge your code. You can request a review from someone specific if you've modified their code - you can see this through git blame and they're also automatically suggested to you by GitHub. Most of the code is reviewed by Brandon (brndnmtthws) as he's the owner of the repo, but it might be a good idea to ask for others to review your code if you aren't completely sure about your changes.

After a review, you'll be able to merge your code. If you notice you've missed something, you can still perform changes without having to go through another review, but be careful not to break something while doing so and get that merged into main as some people build from sources.

Issue Triage

During triage, issues should be labeled with appropriate labels in order to make them visible to the right people at the right time. Adding too many labels to an issue is equally useful as adding none as that makes the issue appear in searches when it shouldn't - so be conservative, but not squeamish about adding them.

Labels are color coded in a way which communicates their purpose:

#ffffff (white) - indicates issue state
#006b75 (cyan) - indicates scope (i.e. which part of conky is affected)
#d93f0b (peach) - indicates issue kind
- #ff0000 (red) - used for bugs
#fbca04 (yellow) - indicates issue priority
#0010A0 (navy) - indicates affected backend or output (X11/Wayland/HTTP server/ncurses/...)

Only one label from each of those categories is appropriate, except for scope. Sometimes people cram in several issues and/or questions in a single ticket, in those cases it's appropriate to use multiple issue kind labels.

There's also some labels with unique colors that don't fit into any of the above categories:

#90f4b3 (green) - good first issue - simple issues that can be fixed by first time contributors
#515508 (sewers) - github_actions - generated by github actions

_{TODO: Create a simple SVG font for color codes because GH wiki sanitizes styles out...}

Issue State

Issue state allows hiding issues that are waiting on reporter (need details), or showing those requiring special attention. It indicates what (if anything) has to be done to progress an issue. Namely:

triage - means the issue hasn't been looked at yet. This means that it's unknown whether the issue is actually valid, what its scope is, what backends have been affected, etc.
need details - mean the contributors are waiting for more details before they can start work on fixing the issue. This is in a way the opposite of triage and allows filtering out (incomplete) issues which can't be fixed at the moment due to lack of information.
help wanted - means none of the contributors who looked at the issue so far could figure out how to properly address it.
stale - means the issue wasn't looked at for over a year. This could, but doesn't necessarily mean the issue is no longer applicable. It does however mean the issue should be looked at and progressed if possible.
wontfix- means the issue will not be fixed. This label is appropriate for cases where:
- What's reported isn't a bug in conky but some other program.
- Issue is caused by user error instead of faulty code.
- Addressing the issue would require unreasonable amount of effort or code, with (in comparison) small benefits.
- Can't be fixed due to external limitations - e.g. X11/Wayland doesn't support certain functionality.
Lack of state label means the issue can be assigned and worked on.

Issue Priority

severe - is used for severe problems which make conky downright unusable make it consistently crash.
- Priority should only be high if the issue is very rare or caused by very specific/unique user setup. For instance, if the crash only occurs with some specific hardware and will be experienced by 0.001% of users.
high - is used for problems which greatly ruin user experience with conky, or crash conky under specific conditions. (Examples: 1)
low - is used for problems that are rarely noticed and don't affect functionality, performance, etc. Example of this is conky incorrectly giving a warning message in the console. (Examples: 1)
Lack of priority label means "normal" priority, i.e. a problem which causes unexpected behavior, but isn't common, can be avoided or affects only part of conky functionality.

_{TODO: Add more examples}

Assigning Issues

You're welcome to assign yourself to issues you're currently working on, but it's better to simply create a development branch for the issue and link the PR. Linking a PR communicates the same sentiment, but it also allows others to continue where you left off in case you're unable to finish your work.

Don't assign issues to other contributors, assignment of issues to others communicates authority or established protocol. As conky is a non-commercial project, everyone is free to work on whichever part of the project they're interested in. There's also no pre-established roles, so it's better to just mention someone if you believe an issue is especially suited for them to solve.

Guides

Build Flags

Conky supports a lot of different features, many of which aren't used by everyone (or even many people). Some features depend on specific kernel options, hardware, installed software, etc. and as such it would break conky for people who don't meet the appropriate environment requirements. In order to deal with this, conky has an extensive list of build flags which can be used to tweak support for such features.

If you're contributing a change which might not work for everyone, or you're adding a new module which queries specific system data, you can easily add new build options in cmake/ConkyBuildOptions.cmake file. There's two ways of doing so:

option(BUILD_WAYLAND "Build Wayland support" true)

dependent_option(OWN_WINDOW "Enable running conky in a dedicated window" true
  "BUILD_X11" false
  "Dedicated window mode only works on X11")

option - an option that doesn't depend on any other
- 1st argument is compile flag name, usually prefixed with BUILD_
- 2nd argument is a human readable (short) description
- 3rd argument is the default value
dependent_option - an option that checks for criteria/dependencies
- first three arguments are the same as for option
- 4th argument is a semicolon (;) separated list of predicates
- 5th argument is the value set if predicates aren't satisfied
- 6th argument is a human readable warning that CMake will report in case predicates aren't satisfied

NOTE: predicates can be any valid CMake boolean expression and don't have to necessarily be previously declared options.

Order of option declaration doesn't matter, they're evaluated by run_dependency_check() at the end of the file and will work so long as there's no dependency cycles between them. Due to implementation details, this entails that option dependency chain can be the length of 10 dependencies at most (can be tweaked if needed).

System Requirements

If the feature you've added requires some additional system dependencies, those can be included in cmake/ConkyPlatformChecks.cmake file. In case of dependent options, guards around platform checks (and rest of the build script) shouldn't check for predicates as those have been previously checked by ConkyBuildOptions.cmake - if they're not met, the build flag is already the value set if predicates aren't satisfied.

_{TODO: Expand section?}

Conky Sources

Finally, if your feature requires some additional source files to be included in the binary, you can add them to src/CMakeLists.txt. Make sure to apply your build flag to these as well. See the rest of the file and existing build flags for reference.

_{TODO: Expand section?}

X11

X11 is notorious for its hard to follow documentation, weird edge cases, variable names, side effects, legacy, etc. It might seem daunting trying to work with it, and you'll likely end up making a mistake. That's how things have always been and that's why Wayland was created. Don't be discouraged by it though, conky was built over a long period of time by many people tweaking and adjusting other contributors' code to make it work just right for everyone (and it's still not perfect). Make sure to test your changes with at least two different WMs and if something doesn't work right off the bat, it can be fixed in one of subsequent versions.

Here are some resources that you might find useful:

The only rule about changes to backends is that they should be somewhat WM/DE agnostic, i.e. code shouldn't explicitly check for the current WM/DE in order to make use of very specific characteristics only supported by a single target. It can if there's no generic way to achieve the same functionality, but generic methods should always be preferred. The only exception to this is the case where a certain (or few) WM/DE supports some extra functionality that isn't at all supported by any other (e.g. scrollable desktop), in which case support for such a feature should be guarded with build flags.

Debugging

Sometimes you might need to examine window trees and properties for specific WMs. In those cases xwininfo is a useful tool for examining windows, their hierarchy and some other information (see man xwininfo).

In case you want to print out a list of atoms/properties that are defined on conky in a specific WM, you can use xprop (see man xprop).

For examining mouse events, you can use the xinput test-xi2 command.

Xlib Error Opcodes

Xlib always gives weird and obscure errors. If built without xcb-util-errors present on the system, conky will only print major and minor error opcode: major opcode describes the protocol that's failing, while the minor opcode describes the request which caused the issue.

Conky already resolves error codes in accordance with X11 spec. Extension protocols have a dynamic major opcodes so they're platform dependent, these include any major opcodes larger than 125. Minor opcodes vary from protocol to protocol, they're not found in documentation, but they can be grepped from X11 header files and are consistent across platforms.

In case you're really struggling to figure out what major and minor mean, you can ask the reporter to build conky with HAVE_XCB_ERRORS by installing xcb-util-errors package before building conky. When this feature is enabled, the library in question should generate descriptive error messages in place of opcodes.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly