SIL Font Development Guide

How to build, modify, and contribute to SIL International font projects

View project onGitHub

3. Repository Structures

Our projects use a consistent directory structure for both our source repositories and release packages. So, if you know your way around one of our projects, you can easily understand all of them. We’d be happy to see others adopt this overall structure, too, so please consider it for your projects.

We talk about repositories because our project directory structures and all the (important) files they contain are tracked with git. We make our repositories available on GitHub, but there’s nothing about our structures or processes that depends on that hosting service.

Each of our projects (which usually contain only a single font family) use a single dedicated project folder that contains all the font sources, so that it remains self-contained. If any common files are shared among multiple projects, then dedicated tools and corresponding documentation will be available inside the project to do a manual synchronisation so that one source checkout always gives you everything you need.

Our convention is to name the project folder font-name-of-font-family as in font-andika-mtihani.

Example structure

Here is an annotated example of our project repository structure based on Andika Mtihani’s public git repository. Files that we normally have in all projects are in bold. All others are optional and may differ from project to project. Files and folders not in the Andika Mtihani project are in (parentheses) and are provided as a guide to other projects.

  • .gitattributes — git attributes configuration hidden file tailored for font projects
  • .gitignore — git ignore configuration hidden file tailored for font projects
  • FONTLOG.txt — font design and engineering-oriented changelog
  • OFL-FAQ.txt — Frequently Asked Questions file for the SIL Open Font License
  • OFL.txt — SIL Open Font License file with the copyright statement(s) in its header
  • preflight — normalization script to be run before testing/committing a change
  • preflightg — script to produce and normalize UFOs from a Glyphs file
  • preflightfl — script to produce and normalize UFOs from a FontLab-produced UFO
  • preflightff — script to produce and normalize UFOs from a Fontforge-produced UFO
  • preglyphs — script to produce temporary Glyphs files from UFOs+designspace
  • README.md — markdown file with minimal information
  • README.txt — more complete README file describing the font project
  • wscript — Smith configuration used for building, testing and releasing
  • ( documentation/ — folder for user documentation )
  • source/ — folder for containing UFOs, designspaces, smart code sources, etc
    • ( AndikaMtihani.feax — OpenType feature code including SIL extensions to .fea )
    • AndikaMtihani-Bold.ufo
    • AndikaMtihani-BoldItalic.ufo
    • AndikaMtihani-Italic.ufo
    • AndikaMtihani-Regular.ufo
    • AndikaMtihaniItalic.designspace — designspace definition for Italic & Bold Italic
    • AndikaMtihaniRoman.designspace — designspace definition for Regular & Bold
    • composites.txt — composite character definitions
    • glyph_data.csv — glyph-specific data such as production glyph names and glyph orders
    • archive/ — folder for legacy formats if needed for archival purposes
    • ( graphite/ — folder for Graphite source code )
    • logs/ — folder for log files, only needed as a placeholder to make tools happy
    • ( masters/ — folder for master UFOs for projects involving interpolated instances )
  • tests/ — folder for various test documents and data files
  • references/ — folder for font binaries used for regression testing
  • ( tools/ — folder for project-specific scripts and utilities )
    • ( fontbakery/ — folder for project-specific fontbakery checks )
    • ( lib/ — folder for project-specific libraries )
  • ( web/ — example files for self-hosted webfonts )

Ignored files: temporary files, generated files

By default, the results generated by a build (including the fonts, various reports and log files) will appear in a separate results/ folder not stored in the git repository. Temporary files and generated artifacts like backups, logs, test results, specimens, etc. are not stored in the git repository and are set to be ignored via the .gitignore configuration file. There is some flexibility though, as certain source files are generated or modified by scripts at various times in the lifecycle of a project.