Contributing to xkeyboard-config

Thank you for your interest in contributing to xkeyboard-config! There are many ways to contribute and we appreciate all of them.

Getting help

First of all, make sure you read the following:

• Code of conduct
• Introduction to XKB
• How to enhance XKB configuration
• The XKB Configuration Guide
• Symbols files
• The XKB file format (exhaustive documentation)

Bug reports

Bugs are reported in our issue tracker.

• Please first check if an existing issue on the topic already exists before creating a new one.
• Please use the appropriate template in the corresponding interface, so that the issue can be efficiently processed.

Making changes to the keyboard database

Getting started

This project is built using meson:

1. Install meson:

   # Recommended: with pipx
   pipx install meson
   # Alternative: with pip
   pip3 install --user meson
   

2. Setup & build:

   # You may choose the install directory with --prefix
   meson setup build --prefix="$PWD/inst"
   meson compile -C build
   

3. Install locally for debugging:

   meson install -C build
   

We ensure our code quality by using pre-commit:

1. Install pre-commit:

   # Recommended: with pipx
   pipx install pre-commit
   # Alternative: with pip
   pip3 install --user pre-commit
   

2. Install the git hook scripts:

   pre-commit install
   

3. The checks will then be run before each commit. You may also run them manually, like so:

   pre-commit run --all
   

Testing

Note: Remember to re-run meson install -C build after each modification and before running the tests!

• With Xorg tools:

  # Compile keymap to a file
  setxkbmap -print -rules "$PWD/inst/share/X11/xkb/rules/evdev" -layout … \
    | xkbcomp -I -I"$PWD/inst/share/X11/xkb" \
        -xkb - /tmp/keymap.xkb
  # Activate keymap
  setxkbmap -print -rules "$PWD/inst/share/X11/xkb/rules/evdev" -layout … \
    | xkbcomp -I -I"$PWD/inst/share/X11/xkb" - "$DISPLAY"
  # Interactive debugging
  xev -event keyboard
  

• With libxkbcommon tools:

  # Compile keymap to a file
  xkbcli compile-keymap --include "$PWD/inst/share/X11/xkb" \
            --layout … > /tmp/keymap.xkb
  # Interactive debugging; require having your user in group “input”
  xkbcli interactive-evdev --include "$PWD/inst/share/X11/xkb" \
            --layout …
  

Guidelines for modifications

[!WARNING] 🚧 Work in progress 🚧

Some rules may be obsolete, we are working on it

Please check if an existing issue or merge request on the topic already exists before creating a new one.

Types

There are no special rules for new types. They are going to be introduced very conservatively.

Geometries

There are relatively few geometry descriptions that are currently available.

The historical XKB format is complex and is considered deprecated. We accept only fixes.

Models

1. Most of PC keyboard models should be defined by the following actions:

   • adding new xkb_symbols section to symbols/inet
   • extending $inetkbds list in rules/base.lists.part
   • adding new model section to rules/base.xml (in modelList)

2. It is recommended to use {v}{m} pattern for the model name, where {v} is abbreviated vendor name. {m} is the model name. Recommended vendor abbreviations:

   • a4tech - A4Tech
   • acer - Acer
   • cherry - Cherry
   • chicony - Chicony
   • compaq - Compaq
   • dell - Dell
   • genius - Genius
   • logi - Logitech
   • microsoft - Microsoft
   • samsung - Samsung

3. The name of xkb_symbols section (in symbols/inet) should be same as the new element in the $inetkbds list (in base.lists.part), same as name element (in base.xml).

4. The vendor element in base.xml has to be specified.

5. While defining xkb_symbols, it is strongly recommended to include (where applicable) shared sections for the media and navigation keys:

   • acpi_common
   • media_common
   • media_acpi_common
   • media_nav_acpi_common
   • media_nav_common
   • nav_common
   • nav_acpi_common

   These sections should be used even if not all of the keys specified in that section are present in the defined model. The syntax is standard:

   include "inet(media_common)"
   

   For example, if keys prev/next/play/stop have the mapping as defined in media_common (and other keys do not exist in the keyboard at all) - this is a good case for including entire media_common anyway

6. The key mappings have to be sorted alphabetically, by the keycode name.

7. If your keyboard model mapping is entirely covered by some existing section symbols/inet (some keycodes may be not actually used by your keyboard), do not create a new section consisting of a single include statement. Instead, create an alias in rules/base.m_s.part file and add it into rules/base.xml, as usual.

Layouts, Variants

1. Every layout/variant has to define a single group: group 1. Layouts with multiple groups are not accepted.

2. Every layout/variant has to be defined for some particular country, it should go into the file symbols/{cc} where {cc} is 2-letter country code from ISO 3166-1 alpha 2. The language-based layout/file names are not accepted. If several countries are using the same layout (for example, several countries share the same language), it should be fully defined for one country only - and included by reference into the files for other countries.

3. Every layout/variant has to be registered in rules/base.xml.

   There is only one exception: default variants. These are the variants which are either marked by the default keyword in the symbols file (it is recommended to put them first and name them basic), or used as default because of some rule in the rules/base file (usually by modifying rules/base.ml_s.part component).

4. There are popular variant names which are used by many countries, so they should be considered as first candidates (where applicable) for new variants. They are:

   • dvorak - for national variants of the Dvorak layout
   • intl - for variants suitable for multiple languages; usually - for the official state language(s) and some other frequently used foreign languages.
   • mac - for variants specific to Macintosh keyboards
   • nodeadkeys - for variants without dead keys (if the some other national variants are using them)
   • phonetic - for variants which are using phonetic resemblance (usually - based on standard Americal layout)
   • sundeadkeys - for variants with dead keys
   • us - for variants which are using standard American layout as a basis, adding some national characters
   • winkeys - for variants which are not standardized nationally but used in Microsoft Windows

5. Every layout/variant has to provide a full description. First - as the group name in the symbols file, second - as the translatable description in rules/base.xml.

   The general approach for the descriptions is to follow “” or <“Language> ()” convention, for example: “English” or “Russian (legacy)”. The usual practice is to use the country name as variation name, for example: “French (Canada)”. The language has to be chosen as the one that is most frequently used with that layout/ variant. That language has to be put first into the languageList attribute in base.xml (if the variant record does not have own languageList, the parent layout’s languages are used).

6. For the layouts/variants that are “exotic”, it is recommended to use base.extras.xml instead of base.xml. The word exotic is used in statistical sense only, e.g. a low users count compare to the other layouts.

   There is no formal definition of exotic, because in most cases it is not possible to prove the actual number of users. There are several “usual suspects” for the exotic section:

   1. The layouts for endangered/extinct languages/scripts. The statistics can be taken from http://www.ethnologue.com/. The potential candidates are languages with <100K speakers. If the number of speakers is <10K, the language most probably belongs to extras

   2. The languages that are used most frequently with layouts made for other languages. If it is more popular to type a language L1 with layouts designed for another language L2, then layouts designed specifically for L1 may be considered as exotic, even if the language L1 itself is popular. A possible scenario is national minorities using the languages with the script similar to the script used by the language of the larger nation in the same country.

   3. The exotic layouts for popular languages. If some relatively small group of people are using some variant suitable for their needs. Typical examples: variants for programmers, for typography, for particular group of sciences, for sacred texts, etc.

   Please note that highly personal or experimental layouts will not be accepted. We have instructions for Xorg and instructions for Wayland to install them locally as user-specific layouts.

   The following table sums up the the previous examples:

   Layout	Language	Speakers	Target use	Users count	Scenario	Layout popularity
   A	L1	<10 K	General (L1)	Low	1	Exotic?
   B	L2	>100 K	General (L2)	Average/High		Normal
   ″	L3	>100 K	General (L3, L2?)	Average	2	Exotic?
   ″	L1	<10 K	General (L1, L2?)	Low	2	Exotic?
   C	L2	>100 K	General (L2)	Low	3	Exotic?
   D	″	>100 K	Niche	Low	3	Exotic?
   E	L1	<10 K	Niche	Very Low	3	Exotic

   That’s typical, but not the only possible scenarios for putting layout/variants into the extras section.

   The maintainers of xkeyboard-config typically question the popularity of newly submitted layouts/variants. If no conclusive proof of number of users is provided, the layout may be:

   • Accepted: the layout can be put into the extras section (the maintainers reserve that right).

   • Rejected: note that this decision may not be final, e.g. the maintainers noted some potential but the layout needs to reach sufficient popularity before being proposed again.

     The layout can still be installed locally as a user-specific layout: we have instructions for Xorg and instructions for Wayland.

   Putting layout/variant into the extras section is just a representation of the fact that layout is not popular enough to be included into the main section. The GUI tools can use any approach to displaying (or not displaying) extras - this issue is out of scope of xkeyboard-config.

   It is recommended to put exotic variants into the end of the corresponding symbols file - after the delimiter line: // EXTRAS:.

7. The short description (shortDescription tag) is recommended for the indicators that use labels (as opposite to flags) for providing the user with the information about currently used layout/variant. This description is expected to contain the 2-letter ISO639-1 code (in lowercase) of the primary language - or, if no ISO639-1 exists for that language, it can be 3-letter code from ISO639-2 or ISO639-3. That code is made translatable, so that localized GUI can display some abbreviations suitable for the current locale. If some variant does not provide own short description, the short description from the parent layout is expected to be used.

8. For layouts/variants using more than 2 shift levels, it is highly recommended to include level3(ralt_switch) symbols definition - for standard switching to levels 3 and 4 using AltGr key.

9. The authors are highly encouraged to use include statements wherever possible – it makes the resulting code more compact and easier to manage.

10. The key mappings have to be sorted alphabetically, by the keycode name.

11. When you contribute model-specific layout/variant (for example, German for Macintosh), try to separate layout-specific mappings from the general ones, common to any national layout on that hardware. Usually, alphanumeric and punctuation key mappings are layout-specific, while navigation keys, functional keys, modifiers etc are model-specific. Consider putting model-specific keys mappings to the model-specific definitions (usually it is a section of symbols/inet file).