Skip to content

Latest commit

 

History

History
67 lines (51 loc) · 2.89 KB

contributing.md

File metadata and controls

67 lines (51 loc) · 2.89 KB
Raw

Contributing

Table of Contents

Metadata

The information for each pictogram that is used by our website is hosted in YAML files inside of the pictograms package, located here. Different files hold different types of information for our pictograms. The most notable ones include:

You can edit each of these files using GitHub UI by clicking on the "edit" pictogram. We go into more detail for each of the file formats below.

pictograms.yml

This file contains information about a pictogram's name, "friendly" name, and aliases. The friendly name for an pictogram is what is displayed to an end-user on our website. The name for an pictogram matches the asset name in our folder of SVG assets. Finally, aliases for a pictogram are used during search as alternative ways of finding the pictogram.

categories.yml

This file contains grouping information for pictograms and the categories, or subcategories, to which they belong. Feel free to add or update categories, subcategories, members, and more in this file.

deprecated.yml

This file contains information mapping assets that have changed in the current release. Typically, this file will indicate which pictograms have been renamed or removed. This file contains a list of deprecated pictograms with a required name field alongside an optional reason field. You can use the reason field to indicate that:

  • The icon has been replaced by an alternate icon
  • The icon has been removed

Use deprecated.yml when assets are renamed to indicate the change. This will hide the deprecated name from display on the web site, and signal to teams that the originally named file is a candidate for future removal. It's recommended that you also add the deprecated name to aliases for the asset in icons.yml, so that the new asset name will be a search result for the deprecated name. We then persist both named assets in the repo for 2 releases to allow teams time to migrate to the new asset name.

When an asset is removed with no replacement, it is also captured in deprecated.yml. Removed icon assets represent breaking changes and should be carefully considered. To remove an asset, add the asset name to deprecated.yml; we then persist the to-be removed assets in the repo for 2 releases to allow teams time to migrate to a different asset.