lib-modules Public

Watch 0 Fork 0 Star 0
markdown · 2692 bytes Raw Blame History

Repo Structure

This document defines how lib-modules is organized.

Repository Type

lib-modules is an umbrella repo, not a traditional shared-history monorepo.

Use this repo for:

  • landscape and roadmap docs
  • package discovery
  • shared naming and release conventions
  • Git submodule pointers to package repos

Do not use this repo as the place where package source code is primarily developed.

Package Model

Each reusable library should have:

  • its own GitHub repository
  • its own fpm.toml
  • its own release tags
  • its own CI
  • its own issue tracker
  • its own README and examples

This repo then includes that package repo as a Git submodule at:

packages/<package-name>

Examples:

packages/fgof-process
packages/fgof-fs
packages/fgof-pty

Why Submodules Instead Of A Flat packages/ Code Monorepo

Submodules are the preferred structure here because they preserve the things that matter most for reusable libraries:

  • package-level discoverability on GitHub
  • clean standalone clone URLs
  • independent commit history
  • independent release cadence
  • easier mental model for outside users

The main downside is submodule workflow friction. That is acceptable here because this root repo is mostly a catalog and coordination layer, not the main day-to-day development surface for every package.

Naming Conventions

Recommended package naming:

  • repo names: fgof-process, fgof-fs, fgof-pty
  • top-level module prefix: fgof_

Examples:

  • repo: fgof-process
  • modules: fgof_process, fgof_process_types

Root Repo Contents

Root-level files should stay focused on:

  • high-signal docs
  • package index or catalog
  • contributor guidance for the umbrella
  • small helper scripts for submodule management

Good root-level files:

  • README.md
  • LANDSCAPE.md
  • docs/REPO-STRUCTURE.md
  • scripts/add-package-submodule.sh

Avoid placing package implementation files directly at the root.

Adding A New Package

Recommended flow:

  1. Create the package as its own repository.
  2. Give it a minimal standalone structure:
    • fpm.toml
    • src/
    • test/
    • README.md
    • CI
  3. Add it here as a submodule under packages/.
  4. Update the root README.md package catalog.
  5. Add any package-specific notes or cross-links if needed.

Cross-Package Dependencies

Prefer:

  • standalone packages first
  • shallow dependency graph
  • shared conventions over shared internal code

Avoid:

  • tight internal coupling between packages
  • hidden assumptions that a package is always checked out inside this umbrella repo

Every package should make sense to someone who finds it on GitHub without ever opening lib-modules.

View source
1 # Repo Structure
2
3 This document defines how `lib-modules` is organized.
4
5 ## Repository Type
6
7 `lib-modules` is an umbrella repo, not a traditional shared-history monorepo.
8
9 Use this repo for:
10
11 - landscape and roadmap docs
12 - package discovery
13 - shared naming and release conventions
14 - Git submodule pointers to package repos
15
16 Do not use this repo as the place where package source code is primarily developed.
17
18 ## Package Model
19
20 Each reusable library should have:
21
22 - its own GitHub repository
23 - its own `fpm.toml`
24 - its own release tags
25 - its own CI
26 - its own issue tracker
27 - its own README and examples
28
29 This repo then includes that package repo as a Git submodule at:
30
31 ```text
32 packages/<package-name>
33 ```
34
35 Examples:
36
37 ```text
38 packages/fgof-process
39 packages/fgof-fs
40 packages/fgof-pty
41 ```
42
43 ## Why Submodules Instead Of A Flat `packages/` Code Monorepo
44
45 Submodules are the preferred structure here because they preserve the things that matter most for reusable libraries:
46
47 - package-level discoverability on GitHub
48 - clean standalone clone URLs
49 - independent commit history
50 - independent release cadence
51 - easier mental model for outside users
52
53 The main downside is submodule workflow friction. That is acceptable here because this root repo is mostly a catalog and coordination layer, not the main day-to-day development surface for every package.
54
55 ## Naming Conventions
56
57 Recommended package naming:
58
59 - repo names: `fgof-process`, `fgof-fs`, `fgof-pty`
60 - top-level module prefix: `fgof_`
61
62 Examples:
63
64 - repo: `fgof-process`
65 - modules: `fgof_process`, `fgof_process_types`
66
67 ## Root Repo Contents
68
69 Root-level files should stay focused on:
70
71 - high-signal docs
72 - package index or catalog
73 - contributor guidance for the umbrella
74 - small helper scripts for submodule management
75
76 Good root-level files:
77
78 - `README.md`
79 - `LANDSCAPE.md`
80 - `docs/REPO-STRUCTURE.md`
81 - `scripts/add-package-submodule.sh`
82
83 Avoid placing package implementation files directly at the root.
84
85 ## Adding A New Package
86
87 Recommended flow:
88
89 1. Create the package as its own repository.
90 2. Give it a minimal standalone structure:
91 - `fpm.toml`
92 - `src/`
93 - `test/`
94 - `README.md`
95 - CI
96 3. Add it here as a submodule under `packages/`.
97 4. Update the root `README.md` package catalog.
98 5. Add any package-specific notes or cross-links if needed.
99
100 ## Cross-Package Dependencies
101
102 Prefer:
103
104 - standalone packages first
105 - shallow dependency graph
106 - shared conventions over shared internal code
107
108 Avoid:
109
110 - tight internal coupling between packages
111 - hidden assumptions that a package is always checked out inside this umbrella repo
112
113 Every package should make sense to someone who finds it on GitHub without ever opening `lib-modules`.