Skip to content

WORKFLOW.md

Latest commit

 

History

History
178 lines (143 loc) · 6.76 KB

WORKFLOW.md

File metadata and controls

178 lines (143 loc) · 6.76 KB

Workflow

Most of this is taken from the CONTRIBUTING.md file from the Simple Icons project

Table of Contents

1. Get software

  1. Download Inkscape. It's free for Windows, Mac, and Linux.
  2. Install svgo (this is used to optimize SVGs)
  3. Install scour on Linux (not sure if this is needed on Windows or Mac)
    • Arch = sudo pacman -S scour python-tinycss2
    • Ubuntu = sudo apt-get install python3-scour python-tinycss2

2. Setup Inkscape

You only need to do this once:

  1. Edit-->Preferences-->Behavior-->Transforms-->Scale stroke width = Enabled

3. Identify icon

Only homelab-related icons will be added (e.g., Burger King will not be added). In addition, the following icons will not be added:

  • Government organizations
  • Flags and banners
  • Universities or educational institutions

When possible, icons should be sought from official sources first, only then falling back on unofficial sources. The order below should be the preferred order.

  1. About pages, Press pages, Media Kits, and Brand Guidelines (example here and here)
  2. Website images (example here)
  3. GitHub repositories (example here)
    • If the main project repo doesn't contain any images, be sure to check for a repo that contains a project website (example here) or a repo that specifically contains branding and icons (example here)
  4. Wikipedia (example here)

4. Adding an icon

  1. Open each file with Inkscape
  2. Resize the document and viewbox to 48x48
  3. Select all elements of the icon and create a group (this helps during resizing/alignment)
  4. Resize the icon to 48x48 (ensuring to retain ratio)
  5. Center the icon on page both horizontally and vertically (the icon should be touching at least two sides of the document now)
  6. Clean up document (File--->Clean Up Document)
  7. Save the SVG file to the assets directory
    1. Be sure to use Optimized SVG filetype
    2. On the SVG Output tab:
      • Check Remove metadata
      • Check Remove comments
      • Uncheck Embed raster images
      • Check Enable viewboxing

5. Name the icon

Each icon will have two names:

  • A filename (e.g., filename.svg)
  • A display name

Adhere to the following rules when choosing filenames:

  1. Use the lowercase ISO basic Latin alphabet with no whitespaces.
    Correct Incorrect
    github.svg GitHub.svg
    microsoftedge.svg microsoft edge.svg
  2. Replace symbols in the brand name with their spelled-out words.
    Correct Incorrect
    cplusplus.svg c++.svg
    diagramsdotnet.svg diagrams.net.svg
  3. Use a dash (-) to indicate a separate version of the icon. 
    bash-dark.svg
bash-light.svg
  4. When a brand is part of the product name, use it in the filename.
    Correct Incorrect
    apachesolr.svg solr.svg

6. Optimizing an icon

  1. Run svgo to optimize the image (the default settings are fine) 
    svgo assets/filename.svg

7. Annotating an icon

Manually check each icon to ensure it HAS these settings:

  • The SVG namespace 
    xmlns="http://www.w3.org/2000/svg"
  • A 48x48 viewbox 
    viewBox="0 0 48 48"

Below is a partial example of a file.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">...</svg>

Manually check each icon to ensure it DOES NOT have these settings:

  • xlink - This is usually caused by cloned shapes. You can remove this by selecting the clones and choosing Edit-->Clone-->Unlink Clone.
    • This might be harder to remove depending on the design. Try your best.
  • height or width - Instead, use viewBox as show above.
  • Make sure there is no png data encoded into each file.

8. Updating the JSON file

Add the icon to the icons.json file. There are four lines for each icon:

  1. Path: The path in the assets directory to the icon
  2. Name: The display name that will be shown in the final markdown file
  3. A link to the source where you found the SVG file
  4. A link to the brand's guidelines
    • If none exist, leave blank
    • The guidelines may be the same as the source

When adding to the icons.json file, use the following guidelines:

  1. Use alphabetical order by the display name (not the filename)
  2. The display name can have symbols (e.g., C++ or Diagrams.net)
  3. Separate version of the icon should have descriptive display names (e.g., Bash (dark) and Bash (light))
  4. The display name should be stylized as per the brand's requirements (e.g., ownCloud instead of OwnCloud)
  5. The display name can have more information about the icon (e.g., the Linux penguin's name is Tux!)

A full example is below:

        {
            "path": "./assets/gimp.svg",
            "name": "GIMP (Wilber)",
            "source": "https://gitlab.gnome.org/Infrastructure/gimp-web/blob/master/themes/newgimp/static/images/gimp.svg",
            "guidelines": "https://www.gimp.org/about/linking.html"
        },

9. Workflow for publishing a new version

  1. Install Python requirements 
    python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
  2. Run the Python script 
    python3 scripts/convert_json.py
  3. Get current git tags 
    git tag
  4. Increment the version number in package.json to match a new git tag
  5. Do git work 
    git add .
git commit -m "Text goes here"
git push
git tag -a X.Y.Z -m "X.Y.Z - Text goes here"
git push origin X.Y.Z
  6. Pushing the new tag will publish the package to NPM