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:

1. Anyone can copy, modify and distribute conky.
2. The license and copyright notice has to be included with each and every distribution of conky.
3. Anyone can use conky software privately.
4. 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.
5. If someone modifies conky and distributes it separately, they have to indicate changes made to the code.
6. Any modifications of conky MUST be distributed with the same license, GPLv3.
7. 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.

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:

• Git website: Installing git
• GitHub: Cloning a repository
• GitHub: Creating a pull request

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.

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
• Lua API
• conky.text variables

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.

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.

It's 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.

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}

Guides

Xlib Error Opcodes

Xlib always gives weird and obscure errors. If built without xcb error utils, conky will only print major and minor error opcode: major opcode describes the protocol that's failing, 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.