Project repository filesystem schema
Penned on the 29th day of May, 2020. It
was a Friday.
A navigable repository must have a predictable layout. This schema defines a final file-folder hierarchy for a complete generic ANSI C project, including all folders and data. It is for ANSI C systems what the Filesystem Hierarchy Standard is for Linux.
To make projects manageable without deferring to meta-build systems like CMake, some sacrifices were made in how development is approached. None of the sacrifices ultimately precludes targeting any platform or architecture of interest (e.g., ARMv6, or Windows 7).
Windows is not considered as a development platform at all. Instead, it is treated as target only, a status held by game consoles like the PlayStation, or mobile operating systems such as Android or iOS. As is SOP with those systems, cross-compilation is used to achieve targeting, mainly using MinGW. The only development OSes supported are GNU/Linux (generically) and Apple’s macOS. We use both homebrew-fetched GNU and LLVM tools, as well as Apple’s Xcode-provided tools.
The project’s Makefile (used for building)
Legal disclaimers and/or code licensing
The README file
Project contributor’s guide
Build guide for users
Installation guide for users
Dotfiles (and folders) in the repository root
- dot only applies in repo root (not just any subfolder)
- upper & lower alphanumeric, plus underscore/dash/dot
- files and folders both
Project sources, and private headers if distinguished from public ones
- subfolder and file names are limited to 8 characters for brevity
- names cannot contain dashes or underscores, for consistency if/when slashes are mutated into underscores
Project API headers
Project documentation, with files corresponding to ones in src/
Utility scripts for project maintenance
“Extra” utility scripts that are useful to maintainers but are not hard dependencies for maintenance
Folder for non-code assets or data, useful for working without git-lfs
Miscellaneous folder, the contents of which may be anything
Addenda for project layouts
There are several additional notes about the schema worth bearing in mind:
- No files in the repository should be executable, except those in
- None of the files are required to exist
- None of the text files in the repository root have extensions
- Source code can have a soft file-module correspondence. With this in mind, text files in
doc/ should correspond to a module name in
src/. These text files may follow the SLI grammar protocol.
- ‘COPYING’ was chosen as the file name for licensing as it is agnostic to the British English and American English spelling differences with ‘licence’/‘license’
- Make was chosen as the build method for several reasons:
- it is not excessively complex
- it is available and mature on Unix-like systems
- it can target other systems with cross-compilation
- it provides a highly scalable declarative recipe language
- If other build systems are needed, dotfiles and
etc/ are at one’s disposal
Project issue labels
When hosted on GitHub or a similar web frontend for Git, projects shall use a collection of tags with predetermined colours for issues and pull requests. These add consistency to the workflow of project developers. There is a group of general tags that cover basic categorisation; these use darker colours and are appropriate for all kinds of repositories. There are two additional categories for specifying operating system and computer architecture; these use lighter colours and may or may not be relevant for a given repository. At a minimum, a repository shall include all of the general tags, and may elect to include some or all of the OS and architecture tags where relevant.
The colour codes are displayed adjacent to the issue names. Simply click the code to copy it to the clipboard.
These are the canonical names and colour codes for system labels.
These are the canonical names and colour codes for system architectures.
References & additional reading
- Network Working Group. “RFC 2119.” Key words for use in RFCs to Indicate Requirement Levels. <https://tools.ietf.org/html/rfc2119>