Skip to content

Latest commit

 

History

History
245 lines (233 loc) · 12.8 KB

CONTRIBUTING.md

File metadata and controls

245 lines (233 loc) · 12.8 KB

Contributing to Devicon

First of all, thanks for taking the time to contribute! This project can only grow and live by your countless contributions. To keep this project maintable we developed some guidelines for contributions.

Table of Content

Overview on Submitting Icon

Here is an overview of what you have to do to submit your icons to the repo.

  1. Create the svgs for each logo versions that you have
  2. Put the svgs for each logo into its own folders in /icons
  3. Update the devicon.json to include the new icon
  4. Create a separated pull request (PR) for each icon (no matter how many versions).
  5. Include the name of the icon in the pull request title. Follow this format: new icon: {{logoName}} ({{versions}})
  6. Optional: Add images of the new icon(s) to the description of the pull request. This would help speed up the review process
  7. Optional: Reference the issues regarding the new icon.
  8. Wait for a repo maintainer to review your changes. They will run a script to check your icons.
  9. If there are no issue, they will accept your PR into the repo. Else, they will let you know and give you a chance to fix it.

Versions and Naming Conventions

Each icon can come in different versions. So far, we have:

  • original: the original logo. Can contains multiple colors. Example
  • original-wordmark: similar to the above but must contain the name of the technology. Example
  • plain: a one-color version of the original logo. Example
  • plain-wordmark: a one-color version of the original logo but with wordmark. Example
  • line: a one-color, line version of the original logo. Example
  • line-wordmark: a one-color, line version of the original logo but with wordmark. Example

It is not mandatory to have 6 versions for each icon. An icon can only have one or two versions available. Just keep in mind that the minimum is 1 and the maximum 6 (for now). You must also have at least one version that can be make into an icon.

The plain and line versions (with or without wordmark) are designed to be available in the final icon font.

The original version are only available in svg format, so they do not need to be as simple and can contain numerous colors.

Some icons are really simple (like the Apple one), so the original version can be used as the plain version and as the icon font. In this case, you'll only need to make only one of the version (either "original" or "plain"). You can then add an alias in the devicon.json so they can be found with either the "original" or "plain" naming convention. Note that this only applies to font icon versions only, not the SVG versions. SVG versions don't need aliases.

SVG Standards

Before you submit your logos/svgs, please ensure that they meet the following standard:

  • The background must be transparent.
  • The plain and line versions (with or without wordmark) need to stay as simple as possible. They must have only one color and the paths are united before exporting to svg.
  • Optimize/compress your SVGs. You can use a service like compressor or SVG Editor.
  • The icon's strokes and texts must be fills. We use Icomoon to make our icon, which has its requirements.
  • Each .svg file contains one version of an icon in a 0 0 128 128 viewbox.
  • The naming convention for the svg file is the following: (icon name)-(original|plain|line)(-wordmark?).

Organizational Guidelines

  • Each icon has its own folder located in the icons folder
  • Each icon folder contains one .eps file and as many .svg files as versions available
  • The .eps file contains all available versions of an icon. Each version is contained in a 128px by 128px artboard

Updating the devicon.json

Before you open a PR into Devicon, you'd have to update the devicon.json. This is essential for our build script to work and to document your work.

Here is the object that each of your logo must have: 

  
    {
        "name": string, // the official name of the technology. Must be lower case, no space and don't have the dash '-' character.
        "tags": string[], // list of tags relating to the technology for search purpose
        "versions": {
            "svg": VersionString[], // list the svgs that you have 
            "font": VersionString[] // list the fonts acceptable versions that you have
        },
        "color": string, // the main color of the logo. Only track 1 color
        "aliases": AliasObj[] // keeps track of the aliases for the font versions ONLY
    }

Here is what VersionString means:

  1. It's the version part of an `svg` file's name
  2. If you have "html5-original", the version string would be "original"
  3. If you have "react-line-wordmark", the version string would be "line-wordmark"
  4. See naming conventions section for more details

Here is the AliasObj interface: 

     
    {
        "base": VersionString, // the base version
        "alias": VersionString // the alias version that's similar to the base version
    }

Example

As an example, let's assume you have created the svgs for Redhat and Amazon Web Services logos.

For the Redhat svg, you have the "original", "original-wordmark", "plain", and "plain-wordmark" versions.

For the Amazon Web Services svgs, you have the following versions: "original", "original-wordmark", "plain-wordmark". The "original" version is simple enough to be a "plain" version as well. Note that we are not using the acronym AWS.

  1. Put the svgs for each logo that you have into its own folders in /icons
    • This means you would create two folders: one for amazonwebservices and one for redhat
    • Note: don't do this in the same commits. We want to have each logo in its own PR so don't create these two folders in the same commit
  2. Update the devicon.json to include the icon (or variations)
    • For the redhat, you would do this 
                
            {
              "name": "redhat",
              "tags": [
                "server",
                "linux"
              ],
              "versions": {
                "svg": [ // here are the versions that are available in svgs
                  "original",
                  "original-wordmark",
                  "plain",
                  "plain-wordmark"
                ],
                "font": [ // here are the versions that will be used to create icons
                  "plain",
                  "plain-wordmark"
                ]
              },
              "color": "#e93442", // note the '#' character
              "aliases": [] // no aliases in this case
            },
    • For the amazonwebservices, you would do this 
                
            {
              "name": "amazonwebservices", 
              "tags": [
                "cloud",
                "hosting",
                "server"
              ],
              "versions": {
                "svg": [ // here are the versions that are available in svgs
                  "original",
                  "original-wordmark",
                  "plain-wordmark"
                ],
                "font": [ // here are the versions that will be used to create icons
                  "original", // "original" is simple enough to be used as the plain icon so we'll add "plain" to the aliases below
                  "plain-wordmark",
                  // note that the alias "plain" is not listed here. It must be listed in the `aliases` attribute
                ]
              },
              "color": "#F7A80D", // note the '#' character
              "aliases": [
                {
                    "base": "original", // here is the base version that we will upload to Icomoon
                    "alias": "plain" // this is its alias. Our script will create a reference so users can search using "original" or "plain" for this icon
                    // note that you don't provide aliases for the svg version. If "original" is not a font version (i.e can't be made into a font), there's no need to provide it with a plain alias
                }
              ]
            }
    • Note: again, don't do this in the same commits. We want to have each logo in its own PR so don't create two folders in the same commit
  3. Create a separate pull request (PR) for each icon (no matter how many variations).
    • This means you would have to create two PRs
    • For Amazon Web Services, the branch name would be icons/amazonwebservices.
    • For Redhat, the branch name would be icons/redhat.
  4. Include the name of the icon in the pull request. Follow this format: "new icon: {{logoName}} ({{versions}})"
    • For Amazon Web Services, your PR title should be "new icon: amazonwebservices (original, original-wordmark, plain-wordmark)"
    • For Redhat, your PR title should be "new icon: redhat (original, original-wordmark, plain, plain-wordmark)"
  5. For the rest of the steps, you can follow Overview on Submitting Icon

Requesting an Icon

When you want to request a new icon please feel free to create a issue following some simple guidelines:

  • Search for other issues already requesting the icon
  • If an issue doesn't exist, create an issue naming it "Icon request: name-of-the-icon".
  • Please create separated issues for each icon
  • optional: Include links where the icon can be found

Regarding The Build Script

To make adding icons easier for repo maintainers, we rely on GitHub Actions, Python, Selenium, and Gulp to automate our tasks.

So far, the tasks in the build script are:

There are also other tasks that we are automating, such as:

  • Ensure code quality is up to standard
  • Upload svgs to icomoon.io and take a screenshot for check.