diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4efc27ec7..45c17487a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,506 +1,7 @@ -

Contributing to Devicon

+# Contributing to Devicon -

This guide has been moved to the Wiki and won't be updated any longer.

-
-

-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. -

+Thanks for taking the time to contribute! This project can only grow and live by your contributions. -

Table of Content

- +Our contributing guidelines live in the [wiki](https://github.com/devicons/devicon/wiki). New to contributing? Start with the [Overview on Submitting Icons](https://github.com/devicons/devicon/wiki/Overview-on-Submitting-Icons). -
-

Terms

-

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

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

What Icons Do We Accept?

-

Devicon only accepts Icons of development languages and tools.

-

Development refers to programming or programming-related jobs.

-

Tools can be software, OS, services, etc. that helps with development. It must be specifically related to development (so software like Microsoft Word or Google Calendar won't be accepted since it's too general).

- -Special Cases (see this discussion for more details) - - - -
-

Requesting an Icon

-

To request an icon, please create an issue in the repository, and follow these guidelines:

- - -
-

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. Follow the convention listed.
    2. -
  2. Put the SVGs of each Icon into its own folders in /icons
    3. -
  3. Update the devicon.json to include the new Icon
    4. -
  4. Create a separated pull request (PR) towards the develop branch for each Icon.
    5. -
  5. Fill out the info as stated in the PR template.
    6. -
  6. Include the name of the Icon in the pull request title in this format: new icon: Icon name (versions)
    7. -
  7. Optional: Reference the issues regarding the new icon and label the PR `feature:icon`.
    8. -
  8. Some bots will check your SVGs. If there are any errors, please fix them as instructed.
    9. -
  9. Wait for a maintainer to review your changes. They will run the peek-bot to check your icons.
    10. -
  10. If there are no issues, they will merge it using squash merging. If there are any problems, they will let you know, and give you a chance to fix them.
    11. -
-

Note: Due to our recent bot upgrades, icon contributors don't have to optimize/minify their SVGs anymore!

- -
-

Versions and Naming Conventions

-

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

- -
- -

Each icon/SVG can come in different versions:

- - - - - - - - - - - -
-

original: the original logo. Can contain multiple colors.

- -

devicon-original.svg

- 		-

plain: a one-color version of the original logo. Note that the icon version will be stripped of all colors so you don't have to strip beforehand.

- -

devicon-plain.svg

- 		-

line: a one-color, line version of the original logo. Note that the icon version will be stripped of all colors so you don't have to strip beforehand.

- -

devicon-line.svg

-
-

original-wordmark: similar to the above but must contain the name of the technology.

- -

devicon-original-wordmark.svg

- 		-

plain-wordmark: similar to the above but must contain the name of the technology. Note that the icon version will be stripped of all colors so you don't have to strip beforehand.

- -

devicon-plain-wordmark.svg

- 		-

line-wordmark: similar to the above but must contain the name of the technology. Note that the icon version will be stripped of all colors so you don't have to strip beforehand.

- -

devicon-line-wordmark.svg

-
-
- -

Notes:

-

- -
-

SVG Standards

-

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

- - -
-

Organizational Guidelines

- - -
-

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: -

- -
-  
-    {
-        // the official name of the technology. Must be lower case, no space and don't have the dash '-' character.
-        "name": string, 
-
-        // list of tags relating to the technology for search purpose
-        "tags": string[], 
-
-        // keep tracks of the different versions that you have.
-        "versions": {
-            // list the SVGs that you have 
-            "SVG": VersionString[], 
-
-            // list the fonts acceptable versions that you have
-            "font": VersionString[] 
-        },
-
-        // the main color of the logo. Only track 1 color
-        "color": string, 
-
-        // keeps track of the aliases for the font versions ONLY
-        // see the Example section for more details
-        // NOTE: this attribute is not required from now on (see this)
-        // it is only being kept for backward compatibility
-        "aliases": AliasObj[] 
-    }
-  
-
- -

- Here is what VersionString means: -

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

- Here is the AliasObj interface: -

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

Example of Submitting An Icon

-

-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 - -
    2. -
  2. - Update the devicon.json - -
    3. -
  3. Create a separate pull request (PR) for each Icon. - -
    4. -
  4. - Include the name of the icon in the pull request. Follow this format: "new icon: Icon name (versions}})" - -
    5. -
  5. For the rest of the steps, you can follow Overview on Submitting Icon
    6. -
- -
-

Updating an Icon

-

- Sometimes, a company will update their logo or someone spotted an error in the SVG/icon that needs to be fixed. This means the current icon in our repository might need an update. The steps to do this is simple: -

-
    -
  1. - Create a new commit to fix the SVGs. -
    2. -
  2. - Open a pull request based on the `develop` branch. -
    3. -
  3. - IMPORTANT: name the pull request update icon: icon-name (versions). Basically, follow the Overview on Submitting Icon but replace the new with update in name of request with the above. -
    4. -
  4. - Follow the rest of the steps as laid out in Overview on Submitting Icon. -
    5. -
- -
-

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.
-

- -
-

The Build Script: how it works and its quirks

-

We rely on GitHub Actions, Python, Selenium, Imgur, and Gulp to automate our tasks. Please feel free to take a look at the workflow files. The codes should be clear enough to follow along.

- -

Here are the main bots/script that we use:

- - -

Here are the modular tasks in the build script:

- - -
-

Common Bugs and Solutions

-

There are some bugs that the build scripts might run into. Listed below are the common ones and their solutions

-
    -
  1. No connection could be made because the target machine actively refused it. (os error 10061) - -
    2. -
  2. SHA Integrity - -
    3. -
  3. Wrong PR Title - -
    4. -
  4. Icon created by Icomoon contains strange lines that aren't in the SVG - -
    5. -
- -

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. -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:

- - -
Release preparation and execution
-
    -
  1. Define the next release version number based on the conventions
    2. -
  2. Checkout development as draft-release branch
    3. -
  3. Bump the package version using npm version vMAJOR.MINOR.PATCH -m "bump npm version to vMAJOR.MINOR.PATCH" (see #487)
    4. -
  4. Push the branch draft-release
    5. -
  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. -
  6. Review and approve the auto-create pull request created by the action of the step above
    7. -
  7. Create a pull request towards development. Mention the release number in the pull request title (like "Build preparation for release vMAJOR.MINOR.PATCH). - -
    8. -
  8. Wait for review and approval of the pull request (you can perform a squash-merge)
    9. -
  9. Once merged create a pull request with BASE master and HEAD development. Copy the description of the earlier pull request.
    10. -
  10. Since it was already approved in the 'development' stage a maintainer is allowed to merge it (DON'T perform a squash-merge).
    11. -
  11. Create a new release using the format "Release vMAJOR.MINOR.PATCH" as tag and release title. Use the earlier created description as description of the release.
    12. -
  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).
    13. -
- -

Recommended resources and tools

- -| Tool Name | Link | Description & Usage | -| :----------------- | :------------------------------------------------- | :------------------------------------------------- | -| Inkscape | https://inkscape.org/ | Desktop application for editing and Making SVG's | -| Visual Studio Code | https://code.visualstudio.com/ | A code editor for editing code | -| vscode.dev | https://vscode.dev/ | Visual Studio Code in the browser | -| Iloveimg | https://www.iloveimg.com/resize-image/resize-svg | Resizing SVG's | -| svgviewer.dev | https://www.svgviewer.dev/ | View, save, and optimize SVGs | +Questions? Ask in [GitHub Discussions](https://github.com/devicons/devicon/discussions) or our [Discord community](https://github.com/devicons/devicon/wiki/Discord-community).