Aquefir

Massively multipurpose software.

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

^Makefile$
The project’s Makefile (used for building)
^COPYING$
Legal disclaimers and/or code licensing
^README$
The README file
^CONTRIBUTING$
Project contributor’s guide
^COMPILING$
Build guide for users
^INSTALL$
Installation guide for users
^\.([A-Za-z0-9_\-\.]+/?)+$
Dotfiles (and folders) in the repository root

Regex breakdown:
- dot only applies in repo root (not just any subfolder)
- upper & lower alphanumeric, plus underscore/dash/dot
- files and folders both

^src/([a-z0-9]{1,8}/)*/[a-z0-9]{1,8}\.[ch]$
Project sources, and private headers if distinguished from public ones

Regex breakdown:
- 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

^include/([a-z0-9]{1,8}/)*[a-z0-9]{1,8}\.h$
Project API headers
^doc/([a-z0-9]{1,8}/)*[a-z0-9]{1,8}\.txt$
Project documentation, with files corresponding to ones in src/
^util/(?!(opt))
Utility scripts for project maintenance
^util/opt/
“Extra” utility scripts that are useful to maintainers but are not hard dependencies for maintenance
^data/
Folder for non-code assets or data, useful for working without git-lfs
^etc/
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:

  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.

bug#BB3425
dependency#92680D
documentation#2B5EA1
duplicate#575757
feature#6B3DCB
help wanted#447E3D
invalid#67503F
question#3B7F71
talk#BA255F
wontfix#9E4818

These are the canonical names and colour codes for system labels.

sys:bsd#C88FF7
sys:linux#A48FF7
sys:macos#8FB0F7
sys:ios#8FCFF7
sys:android#8FF3F7
sys:none#DEDEDE
sys:gba#F7B38F
sys:nds#F7948F
sys:3ds#F78FA5
sys:dos#ACF78F
sys:win32#90F78F
sys:winnt#8FF7C2

These are the canonical names and colour codes for system architectures.

arch:ia32#698CF5
arch:ia64#8969F5
arch:amd64#69B6F5
arch:powerpc#69F1F5
arch:armv4t#F57269
arch:armv5#F59369
arch:armv6#F5C369
arch:armv7#F5E969
arch:aarch64#D5F569
arch:risc-v#F56993

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>