RFC: Should font sources be in repository roots or nested?
Closed this issue · 9 comments
Similar to #19, but for sources.
My vote is to keep the font source files front and center in the root of the repository.
The advantages I see in this are:
-
Discourages people using the "old normal" combo of sub directories for "sources" and "fonts" used by the vast majority of current font projects I see around Github where "sources" may or may not be up to date, may or may not match "fonts", etc. By putting sources at the root it makes it painfully obvious that they are the main attraction in a repository.
-
Less clutter in editors and other UIs that show open file paths. Often long paths are even abbreviated using the trailing path segment for which purpose "sources" is just not useful.
-
Reduced navigation and typing, whether in file managers or Github or the CLI the main thing that's changing and being references should have the most straight forward path.
Clearly the strongest argument in the opposite direction is that to date Google Fonts mandates that font projects use a Repo layout that includes /sources/*. While I plan on campaigning to get them to change that recommended layout so people stop tracking generated binaries in their VCS repositories, I haven't actually campaigned for that yet and not rocking the boat on the sources/ path might make for an easier transition and/or using fontship in addition to whatever Google wants to do.
IMHO, and speaking in broad terms about open source projects, it makes sense for the top-level to be reserved to project metadata files (README, CHANGELOG, CONTRIBUTING, LICENSE, etc.) and project-specific files (sources, docs, tests, etc.) to be contained in appropriately-named directories. I find this approach to be the most flexible and scalable (for example, for font families that contain many variants), as well as adding an extra semantic layer to the repository's file structure.
On a separate note, I also think it is important for collaborative projects to be approachable in order to promote a healthy and sustainable community; and small things like making the structure of the project more obvious at a glance, and having the README not be rendered too far below the fold, are not to be discounted as friction points that add up and may affect a project's growth in the long run. See for example the images I shared in alerque/libertinus#331:
I’m a compulsive organizer. When everything is at the root of a repository, I freak out a bit. In any case, if I’m looking for a file of a certain type, GitHub has a search box and filters.
Than you guys @waldyrious and @fitojb for the feedback. I'm going to sit on this just a bit, but I am warming up to the idea. Not full convinced, but torn. Meta data, specimens, build tooling, everything does start to add up as projects go along and no matter how simple it they start out the tendency is towards clutter. Easing transition for existing projects is also not a trivial reason to consider this.
Another angle to consider here is that from the outset I'm assuming the goal is to handle multiple input formats, with projects being able to pick their own canonical format. A project might call Glyphs canonical, but people should be able to use FontForge to edit glyphs. I'm setting of the various many←→many pathways and trying to normalize so that the canonical format sees the least change, but it's a dicey problem. Using a more than one editor introduces even more source files and even though only one format would be stored in the repository having all those files at the root does start to be a long list.
The UFO format was (in the paper) supposed to solve that, wasn’t it? Like an OpenDocument but for typography.
@fitojb That's the theory. It's not quite there in practice. It's not hopeless, but there are not yet lossless pathways in all directions between other editors. Even between editors using it as their native format their is a tendency for them to clobber each other because the format isn't strict enough. Using a fixed external normalizer gets you most of the way there between UFO capable editors, but 98% isn't game over.
+1 for keeping sources/.
The main issue seems to be having a fonts or build folder with binary files in VCS (which is problematic), that’s unrelated to how sources, assets, tests, tools, and documentations are better organized.
The shortness of path argument is a side effect and doesn’t do much.
Having a structured project is better that having a flat project.
Structure should reflect the architecture.
Sources are a piece of the architecture of a project, just like tests, documentation, tools and other assets.
Okay you guys talked me into it, sources/* will be the default in the next release (with an easy override to set a different source-dir on a per-project basis). It turns out it wouldn't be too hard to detect (how many projects have "*.glyphs" or whatever source files at multiple levels?) but I figured the default and setting was probably better than trying to be to smart and sending some edge case into convulsions.