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.

Developer’s scope

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.

File/folder patterns

Addenda for project layouts

There are several additional notes about the schema worth bearing in mind:

1. No files in the repository should be executable, except those in util/
2. None of the files are required to exist
3. None of the text files in the repository root have extensions
4. 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.
5. ‘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’
6. Make was chosen as the build method for several reasons:
1. it is not excessively complex
2. it is available and mature on Unix-like systems
3. it can target other systems with cross-compilation
4. it provides a highly scalable declarative recipe language
7. 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

1. Network Working Group. “RFC 2119.” Key words for use in RFCs to Indicate Requirement Levels. <https://tools.ietf.org/html/rfc2119>