mirror/devicon
1
0
Fork 0
mirror of https://github.com/konpa/devicon.git synced 2025-01-17 13:38:15 +01:00
Code Issues Releases Wiki Activity
devicon/CONTRIBUTING.md
Amacado b7ce626718 Merge remote-tracking branch 'origin/develop' into amacado/feature/readme-release-strategy 
# Conflicts:
#	CONTRIBUTING.md
2021-04-09 11:26:16 +02:00

20 KiB
Raw Blame History

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 maintainable, we have developed some guidelines for our contributors.

Table of Content

Terms

Here are some terms that we will use in this repo:

  1. "Technology" is used to describe a software, libraries, tool, etc...
  2. "Icon" refers to the svgs and icons version of a technology as a whole.
  3. "SVG/svg" refers to the svg versions of the Icons.
  4. "icon" (lowercase) refers specficially to the font icon versions of the Icons.

Overview on Submitting Icons

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

  1. Create the svgs for each svg versions that you have
  2. Put the svgs of each Icon into its own folders in /icons
  3. Update the devicon.json to include the new Icon
  4. Create a separated pull request (PR) towards the develop branch for each Icon.
  5. Include the name of the Icon in the pull request title in this format: new icon: Icon name (versions)
  6. Optional: Add images of the new svg(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 maintainer to review your changes. They will run a script to check your icons.
  9. If there are no issues, they will accept your pull request and merge it using squash merging. If there are any problems, they will let you know and give you a chance to fix it.

Versions and Naming Conventions

For the technology name, make the file and folder name lowercase and concatenate them. For example:

  • AngularJS becomes angularjs or just angular
  • Amazon Web Services becomes amazonwebservices
  • Microsoft SQL Server becomes microsoftsqlserver

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

  • original: the original logo. Can contain 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

Notes

  • You don't need 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 (ex. Apple), 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 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: this only applies to font icon versions only, not the SVG versions.

SVG Standards

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

  • The background must be transparent.
  • The svg name follows this convention: (Technology name)-(original|plain|line)(-wordmark?).
  • 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. We will strip the color when turning it into icons so they can have any color.
  • Optimize/compress your SVGs. You can use a service like compressor or SVG Editor.
  • The icon's strokes and texts must be fills. This is to satisfy our conversion website's requirements.
  • Each .svg file contains one version of an icon in a 0 0 128 128 viewbox. You can use a service like resize-image for scaling the svg.
  • The svg element does not need the height and width attributes. However, if you do use it, ensure their values are either "128" or "128px". Ex: height="128"
  • Each .svg must use the fill attribute instead of using classes for colors. See here for more details.
  • The naming convention for the svg file is the following: (Technology name)-(original|plain|line)(-wordmark?).

Organizational Guidelines

  • Each icon has its own folder located in the icons folder
  • Each folder may contain one .eps file
    • (optional)
  • The .eps file should contains all available versions of an icon. Each version is contained in a 128px by 128px artboard
  • Each folder must contain all the .svg files for the Icon

Updating the devicon.json

Before you open a PR into Devicon, you must 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 Icon 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 "original", "original-wordmark", "plain-wordmark" versions. 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 Icon in its own PR.
  2. Update the devicon.json
    • For 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" can't be made into a font, there's no need to provide it with a plain alias
                }
              ]
            }
  3. Create a separate pull request (PR) for each Icon.
    • 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: Icon name (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

To request an icon, you can create an issue in the repo. Please follow these 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 a separate issues for each icon
  • Optional: include links where the icon can be found

Maintainer/Reviewer/Teams

Devicon is living by it's contributors and maintainers. Everyone can and is asked to contribute to this project. You don't have to be in a team to contribute!

The branches master and develop are protected branches and only members with corresponding permissions (see teams below) are able to push changes to them. Additional branches must follow the pattern username/feature/description. The /feature/ indicates that a change is made to existing code (regardless if it's a fix, refactor or actual feature). The naming convention is based on the gitflow-workflow.

For organisational purposes we introduced teams with permissions and responsibilities:

Supporter (@devicons/supporter)
Members of this team are responsible for reviewing pull request (auto assigned), managing issues and preparing the upcoming release.
Supporters have Write access to the repository (allowing them to create own branches) and are allowed to push changes to the develop branch (pull request and status checks required).
Maintainer (@devicons/maintainer)
Maintainer role inherits from the 'Supporter' role and adds Maintainer permission to the repository. Members of this team are allowed to publish a new release (push master branch after pull request and status checks).

Wanna join the team? Please open a public discussion where you introduce yourself.
New member requests have to be approved by all active members of the team Maintainer. Every member of this team has a veto permission to reject a new member.

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 to check that it looks good.
  • Comment on the PR so maintainers don't have to manually upload icon result.
  • Publishing a new release to npm; See #288

Discord server

We are running a Discord server. You can go here to talk, discuss, and more with the maintainers and other people, too. Here's the invitation: https://discord.gg/hScy8KWACQ. If you don't have a GitHub account but want to suggest ideas or new icons, you can do that here in our Discord channel. Note that the Discord server is unofficial, and Devicons is still being maintained via GitHub.

Release strategy, conventions, preparation and execution

Release strategy

Devicon does not follow a strict release plan. A new release is depended on current amount of contributions, required bugfixes/patches and will be discussed by the team of maintainers.

Generally speaking: A new release will be published when new icons are added or a bug was fixed. When it's predictable that multiple icons are added in a foreseeable amount of time they are usually wrapped together.

Conventions

The version naming follows the rules of Semantic Versioning. Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality (like a new icon) in a backwards compatible manner, and
  • PATCH version when you make backwards compatible bug fixes.
Release preparation and execution
  1. Define the next release version number based on the conventions
  2. Checkout development as draft-release branch
  3. Bump the package version using npm version vMAJOR.MINOR.PATCH -m "bump npm version to vMAJOR.MINOR.PATCH" (see #487)
  4. Push the branch draft-release
  5. Manually trigger the workflow build_icons.yml (which has a workflow_dispatch event trigger) and select the branch draft-release as target branch. This will build a font version of all icons using icomoon and automatically creates a pull request to merge the build result back into draft-release
  6. Review and approve the auto-create pull request created by the action of the step above
  7. Create a pull request towards development. Mention the release number in the pull request title and add information about all new icons, fixes, features and enhancements in the description of the pull request. It's also a good idea to mention and thank all contributions who participated in the release (take description of #504 as an example).
  8. Wait for review and approval of the pull request (DON'T perform a squash-merge)
  9. Once merged create a pull request with BASE master and HEAD development. Copy the description of the earlier pull request.
  10. Since it was already approved in the 'development' stage a maintainer is allowed to merge it (DON'T perform a squash-merge).
  11. Create a new release using vMAJOR.MINOR.PATCH as tag and release title. Use the earlier created description as description of the release.
  12. Publishing the release will trigger the npm_publish.yml workflow which will execute a npm publish leading to a updated npm package (vMAJOR.MINOR.PATCH).