Guidelines and HOWTOs/Submit an icon

From KDE Community Wiki
Revision as of 19:55, 21 March 2019 by Ndavis (talk | contribs) (→‎Tips and tricks: Add link to Icon Workflow Tips page)
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Get the Breeze Icons git repository

If you already have a KDE development environment set up using the kdesrc-build tool (see https://community.kde.org/Get_Involved/development#One-time_setup:_your_development_environment), then you can get breeze-icons by doing the following:

kdesrc-build breeze-icons

If not, and you aren't interested in setting one up right now, here's how to proceed anyway:

First you need to get the git command line tool, which allows you to interact with reoisitories of source code (and icons!). Open a terminal program such as Konsole, which is shipped by default in most KDE Linux distributions. In the terminal window, type one of the following commands (depending on which Linux distribution you're using) and then press the enter or return key:

  • Arch/Antergos/Manjaro: sudo pacman -S git
  • Fedora: sudo dnf install git
  • KDE Neon/Kubuntu/Ubuntu/Debian: sudo apt install git
  • openSUSE Leap & Tumbleweed: sudo zypper install git


Now for each line below, type the commands and press the enter or return key:

mkdir -p ~/kde/src/
cd ~/kde/src/
git clone git://anongit.kde.org/breeze-icons.git

You have just "cloned" the Breeze Icons git repository to [your home folder]/kde/src/breeze-icons/, which is where it now lives. You can now get on with editing an existing icon or submitting a new one. Explore the folder structure inside [your home folder]/kde/src/breeze-icons/ a bit to get a feel for the structure of the repository--where things live, what kinds of icons go where, and so on. The Breeze Icon design guidelines offer more information, and offer helpful guidelines regarding the style you should match. Always follow the Breeze Icon design guidelines!

KDE icons are SVG files. We recommend the use of Inkscape or another free, open-source vector graphics editor for maximum compatibility.


How to edit an existing icon

Many KDE icons come in multiple versions that are optimized for various sizes, so once you're done editing one version, make sure to edit the others accordingly. For example, if you edit icons/actions/16/document-open-recent.svg, you will also need to edit the versions of that file present in icons/actions/22, icons/actions/16, icons/actions/24, and icons/actions/32.


How to create a new icon

To submit a new icon, first create it in your vector graphics editor, and then once you're done, save it to the appropriate place in the breeze-icons repository. For example if you are submitting a new app icon, you would save it inside [your home folder]/kde/src/breeze-icons/icons/apps/48/. If you are submitting an icon of a type that comes in multiple sizes (for example, an action icon), be sure to save each version to the correct location.


Submit your proposal for review

Once you have edited some icons and/or saved your proposed new icons to the appropriate places, it's time to submit a patch so that the KDE VDG team can review it. Type the following commands in your terminal window, pressing the enter or return key after each line, as before:

cd ~/kde/src/breeze-icons/
git add .
git diff --staged > ~/Desktop/icons.patch

You now have a "patch file" called icons.patch sitting on your desktop. You can now submit this file using Phabricator; see https://community.kde.org/Infrastructure/Phabricator#Posting_a_Patch_using_the_website

Add #vdgas the reviewer. Once you've submitted the patch, please post a comment mentioning your full name and email address.


What happens next

Members of the KDE VDG team will review your patch and propose improvements. This is a conversation that you can and should participate in! If changes are requested, you should make those changes, and re-run the commands that spat out a patch file to generate a new one. Re-submit that new patch file, and keep going until your reviewers are happy. At that point the patch will be landed and you'll officially be a KDE contributor!


Tips and tricks

This whole business of generating patch files gets tedious after a while, doesn't it? Instead, consider setting up the arc command-line tool, which makes it much easier to submit patches. To do that, see https://community.kde.org/Infrastructure/Phabricator#Using_Arcanist_to_post_patches

Also, it's helpful if you go through the full development environment setup (https://community.kde.org/Get_Involved/development#One-time_setup:_your_development_environment) This will allow you compile the tests in the Breeze Icons repo and then run them:

kdesrc-build breeze-icons
cd ~/kde/build/breeze-icons/
ctest

Icon workflow tips for making icon compilation images, optimizing icons and embedding stylesheets: https://community.kde.org/Guidelines_and_HOWTOs/Icon_Workflow_Tips